@catheadowl/pathscope 0.0.0-stage → 0.1.1

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.
Files changed (44) hide show
  1. package/CHANGELOG.md +97 -0
  2. package/LICENSE +21 -0
  3. package/README.md +127 -2
  4. package/dist/cascade.d.ts +16 -0
  5. package/dist/cascade.js +69 -0
  6. package/dist/cascade.js.map +1 -0
  7. package/dist/cjs/cascade.d.ts +16 -0
  8. package/dist/cjs/discover.d.ts +11 -0
  9. package/dist/cjs/engine.d.ts +6 -0
  10. package/dist/cjs/exclusion-engine.d.ts +79 -0
  11. package/dist/cjs/index.d.ts +22 -0
  12. package/dist/cjs/index.js +2102 -0
  13. package/dist/cjs/package.json +1 -0
  14. package/dist/cjs/paths.d.ts +13 -0
  15. package/dist/cjs/presets.d.ts +28 -0
  16. package/dist/cjs/types.d.ts +235 -0
  17. package/dist/cjs/universe.d.ts +27 -0
  18. package/dist/discover.d.ts +11 -0
  19. package/dist/discover.js +66 -0
  20. package/dist/discover.js.map +1 -0
  21. package/dist/engine.d.ts +6 -0
  22. package/dist/engine.js +117 -0
  23. package/dist/engine.js.map +1 -0
  24. package/dist/exclusion-engine.d.ts +79 -0
  25. package/dist/exclusion-engine.js +352 -0
  26. package/dist/exclusion-engine.js.map +1 -0
  27. package/dist/index.d.ts +22 -0
  28. package/dist/index.js +21 -0
  29. package/dist/index.js.map +1 -0
  30. package/dist/paths.d.ts +13 -0
  31. package/dist/paths.js +28 -0
  32. package/dist/paths.js.map +1 -0
  33. package/dist/presets.d.ts +28 -0
  34. package/dist/presets.js +77 -0
  35. package/dist/presets.js.map +1 -0
  36. package/dist/types.d.ts +235 -0
  37. package/dist/types.js +28 -0
  38. package/dist/types.js.map +1 -0
  39. package/dist/universe.d.ts +27 -0
  40. package/dist/universe.js +219 -0
  41. package/dist/universe.js.map +1 -0
  42. package/docs/glossary.md +59 -0
  43. package/docs/semantics.md +73 -0
  44. package/package.json +54 -4
@@ -0,0 +1,73 @@
1
+ ---
2
+ description: How the pathscope exclusion stack layers — preset groups, boundary markers and the full precedence order over one engine
3
+ ---
4
+
5
+ # Semantics
6
+
7
+ How the exclusion stack actually layers. For term definitions read [glossary.md](glossary.md); for signatures and option tables read the `.d.ts` files shipped in the package.
8
+
9
+ ## Precedence
10
+
11
+ The full-stack priority over one engine, strongest first:
12
+
13
+ 1. **Boundary markers** — a marker hit truncates the subtree before any rule table is consulted.
14
+ 2. **strict** — not rescuable by override.
15
+ 3. **override** — final say: rescues everything below, including preset defaults and the dot category.
16
+ 4. **Combined rule table** — presets (front) → gitignore cascade (shallow→deep) → your own exclude rules (rear seat); git last-match-wins.
17
+ 5. **Dot entries** — a walk-layer option, not a gitignore rule.
18
+ 6. **Budget** — orthogonal and loud.
19
+
20
+ ## Presets
21
+
22
+ Five preset groups; mounting is append-only, presets sit at the FRONT of the combined rule table:
23
+
24
+ | Group | Covers |
25
+ | --- | --- |
26
+ | `vcs` | `.git/`, `.hg/`, `.svn/` |
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/` |
30
+ | `agentDocs` | `AGENTS.md`, `CLAUDE.md` (files — agent self-loading instructions, not project content) |
31
+
32
+ ## Boundary markers
33
+
34
+ Markers are existence signals only — content is never interpreted; a hit truncates the whole subtree. (The API names this option `boundaryStones`.)
35
+
36
+ ### Core marker `.git`
37
+
38
+ Always on. An unregistered nested repository — an *embedded repository*, in git's own terminology — truncates the walk, exactly as git never descends into one. Its hit is a fact about territory, not a rule — a gitignore `!.git/` does not rescind it.
39
+
40
+ ### Config-home markers
41
+
42
+ You declare extra marker names via `boundaryStones.configHomes` (may be nested, e.g. `.toolkit/collect.config.toml`): a directory directly containing one marks a separate sub-project and truncates. Config homes are never exemptible — you declared them yourself.
43
+
44
+ ### The `.gitignore` boundary marker
45
+
46
+ Opt-in via `boundaryStones.gitignoreProxy`: treat a nested `.gitignore` as a boundary signal instead of more rules. Off by default — mainstream treats a nested `.gitignore` as rules, not territory. Mounting it under `alignment: 'scanner'` is rejected as a configuration error (the two intentions contradict).
47
+
48
+ ### exempt
49
+
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
+
52
+ ## Scanner semantics
53
+
54
+ With `alignment: 'scanner'` (ripgrep-style):
55
+
56
+ - Nested repositories do not truncate, at any depth.
57
+ - A nested `.gitignore` is rules, not territory.
58
+ - The core marker is **reported but not enforced**: the marker hit stays in the probe contract and keeps naming `.git` — consumer-visible metadata ("this subtree is a nested repository") — while the cut never executes.
59
+ - `exempt` entries targeting the core marker are inert.
60
+ - `gitignoreProxy` is rejected as a configuration error (intentions contradict).
61
+ - On the composable engine, scanner semantics require the ARRAY `stoneHit` form of `excludeDirectory` — the boolean form keeps its unconditional cut.
62
+
63
+ ## Un-exclusion
64
+
65
+ Presets are un-excludable by design: a named negation (`!vendor/`) in any gitignore layer or in your `exclude` option un-excludes a preset entry. There is no wholesale-replacement channel — `mountPresets` is append-only.
66
+
67
+ ## Walk defaults
68
+
69
+ - Output: POSIX relative paths, sorted.
70
+ - `excludeDotEntries` (default `true`): rg `hidden` semantics — a walk-layer option, not a gitignore rule; `override` can rescue dot entries.
71
+ - `respectGitignore: false` skips the gitignore sources only — presets, your own exclude rules, override, and boundary markers adjudicate exactly as before (rg `--no-ignore`).
72
+ - Symlinks are not resolved by default (git/ripgrep default).
73
+ - `walkScope` and `gitUniverse` are mutually exclusive ways to resolve one scope request — no stacking or combination.
package/package.json CHANGED
@@ -1,6 +1,56 @@
1
1
  {
2
2
  "name": "@catheadowl/pathscope",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.1.1",
4
+ "description": "Cross-repo shared engine resolving the in-scope file set: walk, 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
+ "license": "MIT",
6
+ "repository": {
7
+ "type": "git",
8
+ "url": "git+https://github.com/CatheadOwl/pathscope.git"
9
+ },
10
+ "type": "module",
11
+ "engines": {
12
+ "node": ">=20"
13
+ },
14
+ "main": "./dist/index.js",
15
+ "types": "./dist/index.d.ts",
16
+ "files": [
17
+ "dist",
18
+ "docs",
19
+ "CHANGELOG.md"
20
+ ],
21
+ "publishConfig": {
22
+ "access": "public",
23
+ "provenance": false
24
+ },
25
+ "scripts": {
26
+ "build": "tsc -p tsconfig.build.json && node scripts/build-cjs.mjs",
27
+ "typecheck": "tsc --noEmit",
28
+ "test": "node --test \"test/*.test.ts\"",
29
+ "oracle": "node scripts/git-oracle.mjs",
30
+ "oracle:fix": "node scripts/git-oracle.mjs --update",
31
+ "prepack": "pnpm run build && pnpm run test"
32
+ },
33
+ "dependencies": {
34
+ "fdir": "^6.5.0",
35
+ "find-up": "^8.0.0",
36
+ "ignore": "^7.0.13"
37
+ },
38
+ "devDependencies": {
39
+ "@types/node": "^26.6.5",
40
+ "esbuild": "^0.28.2",
41
+ "typescript": "^7.0.2"
42
+ },
43
+ "exports": {
44
+ ".": {
45
+ "import": {
46
+ "types": "./dist/index.d.ts",
47
+ "default": "./dist/index.js"
48
+ },
49
+ "require": {
50
+ "types": "./dist/cjs/index.d.ts",
51
+ "default": "./dist/cjs/index.js"
52
+ }
53
+ },
54
+ "./package.json": "./package.json"
55
+ }
56
+ }