@catheadowl/pathscope 0.1.1 → 0.3.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/dist/cjs/index.js CHANGED
@@ -1413,6 +1413,7 @@ __export(index_exports, {
1413
1413
  PathscopeGitError: () => PathscopeGitError,
1414
1414
  clearUniverseCache: () => clearUniverseCache,
1415
1415
  createExclusionEngine: () => createExclusionEngine,
1416
+ explainScopePath: () => explainScopePath,
1416
1417
  gitUniverse: () => gitUniverse,
1417
1418
  locateNearest: () => locateNearest,
1418
1419
  nodeExclusionIO: () => nodeExclusionIO,
@@ -1437,18 +1438,14 @@ function readGitignoreText(dirPath) {
1437
1438
  function splitLines(text) {
1438
1439
  return text.split(/\r?\n/);
1439
1440
  }
1440
- function reanchorLines(lines, prefix) {
1441
- const out = [];
1442
- for (const line of lines) {
1443
- if (line === "" || line.startsWith("#")) continue;
1444
- const negative = line.startsWith("!");
1445
- const body = negative ? line.slice(1) : line;
1446
- if (body === "") continue;
1447
- const anchored = body.startsWith("/") || body.slice(0, -1).includes("/");
1448
- const reanchored = anchored ? `${prefix}/${body.startsWith("/") ? body.slice(1) : body}` : `${prefix}/**/${body}`;
1449
- out.push(negative ? `!${reanchored}` : reanchored);
1450
- }
1451
- return out;
1441
+ function reanchorLine(line, prefix) {
1442
+ if (line === "" || line.startsWith("#")) return null;
1443
+ const negative = line.startsWith("!");
1444
+ const body = negative ? line.slice(1) : line;
1445
+ if (body === "") return null;
1446
+ const anchored = body.startsWith("/") || body.slice(0, -1).includes("/");
1447
+ const reanchored = anchored ? `${prefix}/${body.startsWith("/") ? body.slice(1) : body}` : `${prefix}/**/${body}`;
1448
+ return negative ? `!${reanchored}` : reanchored;
1452
1449
  }
1453
1450
 
1454
1451
  // src/exclusion-engine.ts
@@ -1477,16 +1474,23 @@ var PRESETS = {
1477
1474
  // Build outputs and coverage. These are collision-grade names (a project's
1478
1475
  // source can legitimately live in `lib/`) — that is exactly why they ride
1479
1476
  // the un-excludable preset channel (`!lib/` names its way out) instead of
1480
- // a separate immune layer.
1481
- dirs: ["dist", "build", "lib", "out", "coverage"]
1477
+ // a separate immune layer. `/target` is the ROOT-ANCHORED cargo/maven
1478
+ // build tree: anchored exactly because `target` is collision-grade — the
1479
+ // Rust toolchain's own adjudication (cargo#3158: a bare `target` hits
1480
+ // same-named directories at any depth; `cargo new` generates `/target`),
1481
+ // so the entry binds only when the scan root itself is the project.
1482
+ dirs: ["dist", "build", "lib", "out", "coverage", "/target"]
1482
1483
  },
1483
1484
  caches: {
1484
- // Python & front-end cache/generated trees. Vendor lineage of the entries:
1485
+ // Cache/generated trees (Python, front-end, build tools). Vendor lineage
1486
+ // of the entries:
1485
1487
  // - repomix `defaultIgnore.ts` (MIT): __pycache__, .mypy_cache,
1486
- // .pytest_cache, .tox, .venv, .cache, .next, .nuxt, .turbo, .vite,
1487
- // .parcel-cache, .svelte-kit
1488
+ // .pytest_cache, .tox, .venv, venv, .gradle, .cache, .next, .nuxt,
1489
+ // .turbo, .vite, .parcel-cache, .svelte-kit
1488
1490
  // - watchfiles `DefaultFilter` (Python-side alignment): __pycache__,
1489
1491
  // .mypy_cache, .pytest_cache, .ruff_cache, .tox, .nox, .venv
1492
+ // (non-dot `venv` and `.gradle` are repomix-only — watchfiles carries
1493
+ // neither; github's Python/Gradle templates carry both)
1490
1494
  // This group is NOT in the default mount set.
1491
1495
  dirs: [
1492
1496
  "__pycache__",
@@ -1495,6 +1499,8 @@ var PRESETS = {
1495
1499
  ".ruff_cache",
1496
1500
  ".tox",
1497
1501
  ".venv",
1502
+ "venv",
1503
+ ".gradle",
1498
1504
  ".cache",
1499
1505
  ".next",
1500
1506
  ".nuxt",
@@ -1628,6 +1634,33 @@ function parentDirKey(key) {
1628
1634
  async function createExclusionEngine(rootKey, options = {}, io = nodeExclusionIO) {
1629
1635
  validateOptions(options);
1630
1636
  const respectGitignore = options.respectGitignore !== false;
1637
+ const asRule = (raw) => raw === "" || raw.startsWith("#") || raw === "!" ? null : raw;
1638
+ const ruleIg = (mounted) => {
1639
+ const ig = (0, import_ignore.default)();
1640
+ ig.add([mounted]);
1641
+ return ig;
1642
+ };
1643
+ const gitignoreRules = (lines, anchor, prefix) => {
1644
+ const out = [];
1645
+ for (const raw of lines) {
1646
+ const mounted = prefix === "" ? asRule(raw) : reanchorLine(raw, prefix);
1647
+ if (mounted === null) continue;
1648
+ out.push({ mounted, original: raw, source: "gitignore", gitignoreAnchor: anchor, ig: ruleIg(mounted) });
1649
+ }
1650
+ return out;
1651
+ };
1652
+ const channelHits = (rules, canonical) => {
1653
+ const hits = [];
1654
+ for (const r of rules) {
1655
+ const t = r.ig.test(canonical);
1656
+ if (!t.ignored && !t.unignored) continue;
1657
+ const hit = { source: r.source, ruleText: r.original };
1658
+ if (r.presetName !== void 0) hit.presetName = r.presetName;
1659
+ if (r.gitignoreAnchor !== void 0) hit.gitignoreAnchor = r.gitignoreAnchor;
1660
+ hits.push(hit);
1661
+ }
1662
+ return hits;
1663
+ };
1631
1664
  let top;
1632
1665
  if (respectGitignore) {
1633
1666
  let dir = rootKey;
@@ -1644,7 +1677,7 @@ async function createExclusionEngine(rootKey, options = {}, io = nodeExclusionIO
1644
1677
  dir = parent;
1645
1678
  }
1646
1679
  }
1647
- const inheritedLines = [];
1680
+ const inheritedRules = [];
1648
1681
  if (top !== void 0 && top !== rootKey) {
1649
1682
  const ancestors = [];
1650
1683
  let cur = parentDirKey(rootKey);
@@ -1654,38 +1687,73 @@ async function createExclusionEngine(rootKey, options = {}, io = nodeExclusionIO
1654
1687
  cur = parentDirKey(cur);
1655
1688
  }
1656
1689
  ancestors.reverse();
1657
- for (const ancestor of ancestors) {
1690
+ for (const [idx, ancestor] of ancestors.entries()) {
1691
+ const hops = ancestors.length - idx;
1692
+ const anchor = `inherited:${Array.from({ length: hops }, () => "..").join("/")}`;
1658
1693
  const text = await io.readGitignore(ancestor);
1659
- if (text !== null) inheritedLines.push(...splitLines(text));
1694
+ if (text === null) continue;
1695
+ for (const raw of splitLines(text)) {
1696
+ const mounted = asRule(raw);
1697
+ if (mounted === null) continue;
1698
+ inheritedRules.push({
1699
+ mounted,
1700
+ original: raw,
1701
+ source: "gitignore",
1702
+ gitignoreAnchor: anchor,
1703
+ ig: ruleIg(mounted)
1704
+ });
1705
+ }
1660
1706
  }
1661
1707
  }
1662
1708
  const rootPrefix = top !== void 0 && rootKey.startsWith(top) ? top : rootKey;
1663
1709
  const offRel = rootKey.slice(rootPrefix.length).replace(/^\//, "");
1664
1710
  const toCanonical = (rel) => offRel === "" ? rel : `${offRel}/${rel}`;
1665
- const mount = (patterns, relDir = "") => {
1666
- const prefix = joinPosix(offRel, relDir);
1667
- return prefix === "" ? patterns : reanchorLines(patterns, prefix);
1668
- };
1711
+ const mountOne = (pattern) => offRel === "" ? pattern : reanchorLine(pattern, offRel);
1669
1712
  const core = (0, import_ignore.default)();
1670
- const presetPatterns = compilePresetPatterns(options.mountPresets ?? DEFAULT_MOUNTED_PRESETS);
1671
- if (presetPatterns.length > 0) core.add(mount(presetPatterns));
1672
- if (inheritedLines.length > 0) core.add(inheritedLines);
1713
+ const coreRules = [];
1714
+ for (const pName of options.mountPresets ?? DEFAULT_MOUNTED_PRESETS) {
1715
+ const preset = PRESETS[pName];
1716
+ for (const dir of preset.dirs) {
1717
+ const mounted = mountOne(`${dir}/`);
1718
+ coreRules.push({ mounted, original: `${dir}/`, source: "preset", presetName: pName, ig: ruleIg(mounted) });
1719
+ }
1720
+ for (const file of preset.files ?? []) {
1721
+ const mounted = mountOne(file);
1722
+ coreRules.push({ mounted, original: file, source: "preset", presetName: pName, ig: ruleIg(mounted) });
1723
+ }
1724
+ }
1725
+ coreRules.push(...inheritedRules);
1673
1726
  const rootIgnoreText = respectGitignore ? await io.readGitignore(rootKey) : null;
1674
1727
  if (rootIgnoreText !== null) {
1675
- const lines = mount(splitLines(rootIgnoreText));
1676
- if (lines.length > 0) core.add(lines);
1728
+ coreRules.push(...gitignoreRules(splitLines(rootIgnoreText), "", offRel));
1677
1729
  }
1730
+ if (coreRules.length > 0) core.add(coreRules.map((r) => r.mounted));
1678
1731
  const policy = (0, import_ignore.default)();
1732
+ const policyRules = [];
1679
1733
  if (options.exclude !== void 0 && options.exclude.length > 0) {
1680
- policy.add(mount(options.exclude));
1734
+ for (const pattern of options.exclude) {
1735
+ const mounted = mountOne(pattern);
1736
+ policyRules.push({ mounted, original: pattern, source: "policy", ig: ruleIg(mounted) });
1737
+ }
1738
+ policy.add(policyRules.map((r) => r.mounted));
1681
1739
  }
1682
1740
  const overrideIg = (0, import_ignore.default)();
1741
+ const overrideRules = [];
1683
1742
  if (options.override !== void 0 && options.override.length > 0) {
1684
- overrideIg.add(mount(options.override));
1743
+ for (const pattern of options.override) {
1744
+ const mounted = mountOne(pattern);
1745
+ overrideRules.push({ mounted, original: pattern, source: "override", ig: ruleIg(mounted) });
1746
+ }
1747
+ overrideIg.add(overrideRules.map((r) => r.mounted));
1685
1748
  }
1686
1749
  const strictIg = (0, import_ignore.default)();
1750
+ const strictRules = [];
1687
1751
  if (options.strict !== void 0 && options.strict.length > 0) {
1688
- strictIg.add(mount(options.strict.map((rule) => rule.pattern)));
1752
+ for (const rule of options.strict) {
1753
+ const mounted = mountOne(rule.pattern);
1754
+ strictRules.push({ mounted, original: rule.pattern, source: "strict", ig: ruleIg(mounted) });
1755
+ }
1756
+ strictIg.add(strictRules.map((r) => r.mounted));
1689
1757
  }
1690
1758
  const configHomes = options.boundaryStones?.configHomes ?? [];
1691
1759
  const gitignoreProxy = options.boundaryStones?.gitignoreProxy === true;
@@ -1707,61 +1775,115 @@ async function createExclusionEngine(rootKey, options = {}, io = nodeExclusionIO
1707
1775
  };
1708
1776
  const exemptibleNames = gitignoreProxy ? /* @__PURE__ */ new Set([".git", ".gitignore"]) : /* @__PURE__ */ new Set([".git"]);
1709
1777
  const unenforcedNames = options.alignment === "scanner" ? /* @__PURE__ */ new Set([".git"]) : null;
1710
- const stoneTruncates = (hit, key) => {
1711
- if (hit === true) return true;
1712
- if (hit == null || !Array.isArray(hit) || hit.length === 0) return false;
1778
+ const stoneDetail = (hit, relDir) => {
1779
+ if (hit == null || hit === false) return [];
1780
+ if (hit === true) return [{ enforced: true }];
1713
1781
  let names = hit;
1714
- if (isExemptDir(key.slice(rootKey.length + 1))) {
1782
+ if (isExemptDir(relDir)) {
1715
1783
  names = names.filter((name) => !exemptibleNames.has(name));
1716
1784
  }
1717
1785
  if (unenforcedNames !== null) {
1718
1786
  names = names.filter((name) => !unenforcedNames.has(name));
1719
1787
  }
1720
- return names.length > 0;
1788
+ const enforcedSet = new Set(names);
1789
+ return hit.map((name) => ({ stoneName: name, enforced: enforcedSet.has(name) }));
1721
1790
  };
1791
+ const stoneHitEntries = (detail) => detail.map((d) => {
1792
+ const hit = { source: "stone", enforced: d.enforced };
1793
+ if (d.stoneName !== void 0) hit.stoneName = d.stoneName;
1794
+ return hit;
1795
+ });
1722
1796
  const combinedExcludes = (canonical) => {
1723
1797
  const policyResult = policy.test(canonical);
1724
1798
  if (policyResult.ignored) return true;
1725
1799
  if (policyResult.unignored) return false;
1726
1800
  return core.test(canonical).ignored;
1727
1801
  };
1802
+ const adjudicateDirectoryImpl = (name, dirPath, stoneHit) => {
1803
+ const key = dirPath.replace(/\/+$/, "");
1804
+ const relDir = key === rootKey ? "" : key.slice(rootKey.length + 1);
1805
+ const hits = [];
1806
+ if (key !== rootKey) {
1807
+ const stones = stoneHitEntries(stoneDetail(stoneHit, relDir));
1808
+ hits.push(...stones);
1809
+ if (stones.some((h) => h.enforced)) return { excluded: true, hits };
1810
+ }
1811
+ const canonicalDir = toCanonical(`${relDir}/`);
1812
+ hits.push(...channelHits(strictRules, canonicalDir));
1813
+ if (strictIg.test(canonicalDir).ignored) return { excluded: true, hits };
1814
+ if (overrideIg.test(canonicalDir).ignored) {
1815
+ hits.push(...channelHits(overrideRules, canonicalDir));
1816
+ return { excluded: false, hits };
1817
+ }
1818
+ hits.push(...channelHits(coreRules, canonicalDir));
1819
+ hits.push(...channelHits(policyRules, canonicalDir));
1820
+ const policyResult = policy.test(canonicalDir);
1821
+ if (policyResult.ignored) return { excluded: true, hits };
1822
+ if (policyResult.unignored) {
1823
+ if (core.test(canonicalDir).ignored) {
1824
+ core.add(`!/${canonicalDir}`);
1825
+ }
1826
+ } else if (core.test(canonicalDir).ignored) {
1827
+ return { excluded: true, hits };
1828
+ }
1829
+ if (excludeDotEntries && name.startsWith(".")) {
1830
+ hits.push({ source: "dot" });
1831
+ return { excluded: true, hits };
1832
+ }
1833
+ return { excluded: false, hits };
1834
+ };
1835
+ const adjudicateFileImpl = (relPath) => {
1836
+ const canonical = toCanonical(relPath);
1837
+ const hits = [];
1838
+ hits.push(...channelHits(strictRules, canonical));
1839
+ if (strictIg.test(canonical).ignored) return { admitted: false, hits };
1840
+ if (overrideIg.test(canonical).ignored) {
1841
+ hits.push(...channelHits(overrideRules, canonical));
1842
+ return { admitted: true, hits };
1843
+ }
1844
+ hits.push(...channelHits(coreRules, canonical));
1845
+ hits.push(...channelHits(policyRules, canonical));
1846
+ if (combinedExcludes(canonical)) return { admitted: false, hits };
1847
+ if (excludeDotEntries && baseNamePosix(relPath).startsWith(".")) {
1848
+ hits.push({ source: "dot" });
1849
+ return { admitted: false, hits };
1850
+ }
1851
+ return { admitted: true, hits };
1852
+ };
1728
1853
  return {
1729
1854
  rootKey,
1730
1855
  stoneNames,
1731
1856
  excludeDirectory(name, dirPath, stoneHit) {
1732
- const key = dirPath.replace(/\/+$/, "");
1733
- if (key !== rootKey && stoneTruncates(stoneHit, key)) return true;
1734
- const relDir = key.slice(rootKey.length + 1);
1735
- const canonicalDir = toCanonical(`${relDir}/`);
1736
- if (strictIg.test(canonicalDir).ignored) return true;
1737
- if (overrideIg.test(canonicalDir).ignored) return false;
1738
- const policyResult = policy.test(canonicalDir);
1739
- if (policyResult.ignored) return true;
1740
- if (policyResult.unignored) {
1741
- if (core.test(canonicalDir).ignored) {
1742
- core.add(`!/${canonicalDir}`);
1743
- }
1744
- } else if (core.test(canonicalDir).ignored) {
1745
- return true;
1746
- }
1747
- if (excludeDotEntries && name.startsWith(".")) return true;
1748
- return false;
1857
+ return adjudicateDirectoryImpl(name, dirPath, stoneHit).excluded;
1749
1858
  },
1750
1859
  foldGitignore(dirPath, text) {
1751
1860
  if (text == null || !respectGitignore) return;
1752
1861
  const key = dirPath.replace(/\/+$/, "");
1753
1862
  if (key === rootKey) return;
1754
1863
  const relDir = key.slice(rootKey.length + 1);
1755
- const lines = mount(splitLines(text), relDir);
1756
- if (lines.length > 0) core.add(lines);
1864
+ const rules = gitignoreRules(splitLines(text), relDir, joinPosix(offRel, relDir));
1865
+ if (rules.length > 0) {
1866
+ core.add(rules.map((r) => r.mounted));
1867
+ coreRules.push(...rules);
1868
+ }
1757
1869
  },
1758
1870
  admitFile(relPath) {
1759
- const canonical = toCanonical(relPath);
1760
- if (strictIg.test(canonical).ignored) return false;
1761
- if (overrideIg.test(canonical).ignored) return true;
1762
- if (combinedExcludes(canonical)) return false;
1763
- if (excludeDotEntries && baseNamePosix(relPath).startsWith(".")) return false;
1764
- return true;
1871
+ return adjudicateFileImpl(relPath).admitted;
1872
+ },
1873
+ adjudicateDirectory(name, dirPath, stoneHit) {
1874
+ return adjudicateDirectoryImpl(name, dirPath, stoneHit);
1875
+ },
1876
+ adjudicateFile(relPath) {
1877
+ return adjudicateFileImpl(relPath);
1878
+ },
1879
+ attributeStones(relDir, stoneHit) {
1880
+ if (relDir === "") return [];
1881
+ return stoneHitEntries(stoneDetail(stoneHit, relDir));
1882
+ },
1883
+ adjudicateStrict(relPath, isDir) {
1884
+ const trimmed = relPath.replace(/\/+$/, "");
1885
+ const canonical = toCanonical(isDir ? `${trimmed}/` : trimmed);
1886
+ return { hit: strictIg.test(canonical).ignored, hits: channelHits(strictRules, canonical) };
1765
1887
  }
1766
1888
  };
1767
1889
  }
@@ -1784,13 +1906,23 @@ async function walkScope(root, options = {}) {
1784
1906
  return hits;
1785
1907
  };
1786
1908
  const diagnostics = [];
1909
+ const stoneReport = [];
1787
1910
  const controller = new AbortController();
1788
1911
  const maxFiles = options.maxFiles ?? DEFAULT_MAX_FILES;
1789
1912
  let included = 0;
1790
1913
  let budgetCut = false;
1791
1914
  const excludeDirectory = (dirName, dirPath) => {
1792
1915
  const key = dirPath.replace(/\/+$/, "");
1793
- if (engine.excludeDirectory(dirName, key, stoneHits(key))) return true;
1916
+ const hits = stoneHits(key);
1917
+ if (key !== scanKey && hits.length > 0) {
1918
+ const relDir = key.slice(scanKey.length + 1);
1919
+ for (const hit of engine.attributeStones(relDir, hits)) {
1920
+ if (hit.stoneName !== void 0) {
1921
+ stoneReport.push({ stoneName: hit.stoneName, path: relDir, enforced: hit.enforced === true });
1922
+ }
1923
+ }
1924
+ }
1925
+ if (engine.excludeDirectory(dirName, key, hits)) return true;
1794
1926
  engine.foldGitignore(key, readGitignoreText(key));
1795
1927
  return false;
1796
1928
  };
@@ -1822,12 +1954,123 @@ async function walkScope(root, options = {}) {
1822
1954
  // the budget, not per-directory I/O errors.
1823
1955
  suppressErrors: true
1824
1956
  }).withRelativePaths().filter((path3) => keepFile(path3)).crawl(rootNative).withPromise();
1825
- return { files: [...files].sort(), diagnostics };
1957
+ stoneReport.sort(
1958
+ (a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : a.stoneName < b.stoneName ? -1 : a.stoneName > b.stoneName ? 1 : 0
1959
+ );
1960
+ return { files: [...files].sort(), diagnostics, stoneHits: stoneReport };
1961
+ }
1962
+
1963
+ // src/explain.ts
1964
+ var import_node_fs4 = require("node:fs");
1965
+ var import_node_path3 = require("node:path");
1966
+ function parseRelPath(relPath) {
1967
+ if (typeof relPath !== "string") {
1968
+ throw new PathscopeConfigError("relPath must be a scan-root-relative POSIX path string");
1969
+ }
1970
+ if (relPath.includes("\\")) {
1971
+ throw new PathscopeConfigError(`relPath "${relPath}" contains a backslash \u2014 pass POSIX-separator form`);
1972
+ }
1973
+ if (relPath.startsWith("/")) {
1974
+ throw new PathscopeConfigError(`relPath "${relPath}" is absolute \u2014 pass a scan-root-RELATIVE path`);
1975
+ }
1976
+ const isDir = relPath.endsWith("/");
1977
+ let core = relPath;
1978
+ while (core.startsWith("./")) core = core.slice(2);
1979
+ if (core === "." || core === "") return { segments: [], isDir: true, isRoot: true };
1980
+ const segments = core.replace(/\/+$/, "").split("/");
1981
+ for (const seg of segments) {
1982
+ if (seg === "") {
1983
+ throw new PathscopeConfigError(`relPath "${relPath}" has an empty segment (double slash)`);
1984
+ }
1985
+ if (seg === "." || seg === "..") {
1986
+ throw new PathscopeConfigError(`relPath "${relPath}" escapes the scan root (".", ".." segments)`);
1987
+ }
1988
+ }
1989
+ return { segments, isDir, isRoot: false };
1990
+ }
1991
+ async function explainScopePath(root, relPath, options = {}) {
1992
+ const { segments, isDir, isRoot } = parseRelPath(relPath);
1993
+ const rootNative = (0, import_node_path3.resolve)(root);
1994
+ if (!(0, import_node_fs4.existsSync)(rootNative)) {
1995
+ throw new PathscopeConfigError(`scan root does not exist: ${rootNative}`);
1996
+ }
1997
+ const baseKey = rootNative.replace(/\\/g, "/").replace(/\/+$/, "");
1998
+ const engine = await createExclusionEngine(baseKey, options);
1999
+ const io = nodeExclusionIO;
2000
+ const probeStones = async (dirKey) => {
2001
+ const hits = [];
2002
+ for (const name of engine.stoneNames) {
2003
+ if (await io.exists(dirKey, name)) hits.push(name);
2004
+ }
2005
+ return hits;
2006
+ };
2007
+ const withPath = (hits, path3) => hits.map((h) => ({ ...h, path: path3 }));
2008
+ if (isRoot) {
2009
+ return { excluded: false, structural: false, hitChain: [], explicit: { pierceable: true, blockers: [] } };
2010
+ }
2011
+ const hitChain = [];
2012
+ const blockers = [];
2013
+ const keys = [];
2014
+ let key = baseKey;
2015
+ for (const seg of segments) {
2016
+ key = `${key}/${seg}`;
2017
+ keys.push(key);
2018
+ }
2019
+ let excluded;
2020
+ let structural = false;
2021
+ let stoppedDepth = -1;
2022
+ for (let i = 0; i < segments.length; i++) {
2023
+ const name = segments[i];
2024
+ const relHere = segments.slice(0, i + 1).join("/");
2025
+ const isLeaf = i === segments.length - 1;
2026
+ const adjudicateAsDir = isLeaf ? isDir : true;
2027
+ if (adjudicateAsDir) {
2028
+ const stoneHit = await probeStones(keys[i]);
2029
+ const adj = engine.adjudicateDirectory(name, keys[i], stoneHit);
2030
+ hitChain.push(...withPath(adj.hits, relHere));
2031
+ if (adj.excluded) {
2032
+ excluded = true;
2033
+ structural = true;
2034
+ stoppedDepth = i;
2035
+ break;
2036
+ }
2037
+ engine.foldGitignore(keys[i], await io.readGitignore(keys[i]));
2038
+ if (isLeaf) excluded = false;
2039
+ } else {
2040
+ const adj = engine.adjudicateFile(relHere);
2041
+ hitChain.push(...withPath(adj.hits, relHere));
2042
+ excluded = !adj.admitted;
2043
+ }
2044
+ }
2045
+ for (const hit of hitChain) {
2046
+ if (hit.source === "strict" || hit.source === "stone" && hit.enforced !== false) {
2047
+ blockers.push(hit);
2048
+ }
2049
+ }
2050
+ if (stoppedDepth >= 0 && stoppedDepth < segments.length - 1) {
2051
+ for (let j = stoppedDepth + 1; j < segments.length; j++) {
2052
+ const relHere = segments.slice(0, j + 1).join("/");
2053
+ const isLeaf = j === segments.length - 1;
2054
+ const asDir = isLeaf ? isDir : true;
2055
+ if (asDir) {
2056
+ blockers.push(...withPath(engine.attributeStones(relHere, await probeStones(keys[j])), relHere));
2057
+ blockers.push(...withPath(engine.adjudicateStrict(relHere, true).hits, relHere));
2058
+ } else {
2059
+ blockers.push(...withPath(engine.adjudicateStrict(relHere, false).hits, relHere));
2060
+ }
2061
+ }
2062
+ }
2063
+ return {
2064
+ excluded: excluded ?? false,
2065
+ structural,
2066
+ hitChain,
2067
+ explicit: { pierceable: blockers.length === 0, blockers }
2068
+ };
1826
2069
  }
1827
2070
 
1828
2071
  // src/universe.ts
1829
2072
  var import_node_child_process = require("node:child_process");
1830
- var import_node_path3 = require("node:path");
2073
+ var import_node_path4 = require("node:path");
1831
2074
  var import_ignore2 = __toESM(require_ignore(), 1);
1832
2075
  var repoRootCache = /* @__PURE__ */ new Map();
1833
2076
  function clearUniverseCache() {
@@ -1900,8 +2143,8 @@ function filterDiffRawRecords(stdout) {
1900
2143
  return [...kept];
1901
2144
  }
1902
2145
  function rebaseToRoot(repoRootNative, rootAbs, repoRelPosix) {
1903
- const rel = (0, import_node_path3.relative)(rootAbs, (0, import_node_path3.join)(repoRootNative, repoRelPosix));
1904
- if (rel === "" || (0, import_node_path3.isAbsolute)(rel) || rel.startsWith("..")) return null;
2146
+ const rel = (0, import_node_path4.relative)(rootAbs, (0, import_node_path4.join)(repoRootNative, repoRelPosix));
2147
+ if (rel === "" || (0, import_node_path4.isAbsolute)(rel) || rel.startsWith("..")) return null;
1905
2148
  return toPosix(rel);
1906
2149
  }
1907
2150
  function validateFilter(filter) {
@@ -1935,7 +2178,7 @@ async function gitUniverse(root, options = {}) {
1935
2178
  );
1936
2179
  }
1937
2180
  if (options.filter !== void 0) validateFilter(options.filter);
1938
- const rootAbs = (0, import_node_path3.resolve)(root);
2181
+ const rootAbs = (0, import_node_path4.resolve)(root);
1939
2182
  const repoRoot = repoRootOf(rootAbs);
1940
2183
  let repoRelative;
1941
2184
  if (variant === "staged") {
@@ -1961,15 +2204,15 @@ async function gitUniverse(root, options = {}) {
1961
2204
  }
1962
2205
 
1963
2206
  // src/discover.ts
1964
- var import_node_path6 = require("node:path");
2207
+ var import_node_path7 = require("node:path");
1965
2208
 
1966
2209
  // node_modules/.pnpm/find-up@8.0.0/node_modules/find-up/index.js
1967
- var import_node_path5 = __toESM(require("node:path"), 1);
2210
+ var import_node_path6 = __toESM(require("node:path"), 1);
1968
2211
 
1969
2212
  // node_modules/.pnpm/locate-path@8.0.0/node_modules/locate-path/index.js
1970
2213
  var import_node_process = __toESM(require("node:process"), 1);
1971
- var import_node_path4 = __toESM(require("node:path"), 1);
1972
- var import_node_fs4 = __toESM(require("node:fs"), 1);
2214
+ var import_node_path5 = __toESM(require("node:path"), 1);
2215
+ var import_node_fs5 = __toESM(require("node:fs"), 1);
1973
2216
  var import_node_url = require("node:url");
1974
2217
  var typeMappings = {
1975
2218
  directory: "isDirectory",
@@ -1990,10 +2233,10 @@ function locatePathSync(paths, {
1990
2233
  } = {}) {
1991
2234
  checkType(type);
1992
2235
  cwd = toPath(cwd);
1993
- const statFunction = allowSymlinks ? import_node_fs4.default.statSync : import_node_fs4.default.lstatSync;
2236
+ const statFunction = allowSymlinks ? import_node_fs5.default.statSync : import_node_fs5.default.lstatSync;
1994
2237
  for (const path_ of paths) {
1995
2238
  try {
1996
- const stat = statFunction(import_node_path4.default.resolve(cwd, path_), {
2239
+ const stat = statFunction(import_node_path5.default.resolve(cwd, path_), {
1997
2240
  throwIfNoEntry: false
1998
2241
  });
1999
2242
  if (!stat) {
@@ -2020,9 +2263,9 @@ var TEN_MEGABYTES_IN_BYTES = 10 * 1024 * 1024;
2020
2263
  // node_modules/.pnpm/find-up@8.0.0/node_modules/find-up/index.js
2021
2264
  var findUpStop = /* @__PURE__ */ Symbol("findUpStop");
2022
2265
  function findUpMultipleSync(name, options = {}) {
2023
- let directory = import_node_path5.default.resolve(toPath2(options.cwd) ?? "");
2024
- const { root } = import_node_path5.default.parse(directory);
2025
- const stopAt = import_node_path5.default.resolve(directory, toPath2(options.stopAt) ?? root);
2266
+ let directory = import_node_path6.default.resolve(toPath2(options.cwd) ?? "");
2267
+ const { root } = import_node_path6.default.parse(directory);
2268
+ const stopAt = import_node_path6.default.resolve(directory, toPath2(options.stopAt) ?? root);
2026
2269
  const limit = options.limit ?? Number.POSITIVE_INFINITY;
2027
2270
  const paths = [name].flat();
2028
2271
  const runMatcher = (locateOptions) => {
@@ -2042,12 +2285,12 @@ function findUpMultipleSync(name, options = {}) {
2042
2285
  break;
2043
2286
  }
2044
2287
  if (foundPath) {
2045
- matches.push(import_node_path5.default.resolve(directory, foundPath));
2288
+ matches.push(import_node_path6.default.resolve(directory, foundPath));
2046
2289
  }
2047
2290
  if (directory === stopAt || matches.length >= limit) {
2048
2291
  break;
2049
2292
  }
2050
- directory = import_node_path5.default.dirname(directory);
2293
+ directory = import_node_path6.default.dirname(directory);
2051
2294
  }
2052
2295
  return matches;
2053
2296
  }
@@ -2083,7 +2326,7 @@ function locateNearest(names, options = {}) {
2083
2326
  (name) => foundPosix.length >= suffixOf(name).length && fold(foundPosix.slice(foundPosix.length - suffixOf(name).length)) === fold(suffixOf(name))
2084
2327
  );
2085
2328
  if (hit === void 0) {
2086
- return { name: (0, import_node_path6.basename)(found), path: found };
2329
+ return { name: (0, import_node_path7.basename)(found), path: found };
2087
2330
  }
2088
2331
  return { name: hit, path: found };
2089
2332
  }
@@ -2095,6 +2338,7 @@ function locateNearest(names, options = {}) {
2095
2338
  PathscopeGitError,
2096
2339
  clearUniverseCache,
2097
2340
  createExclusionEngine,
2341
+ explainScopePath,
2098
2342
  gitUniverse,
2099
2343
  locateNearest,
2100
2344
  nodeExclusionIO,
@@ -11,15 +11,23 @@
11
11
  import type { PresetName } from './types.ts';
12
12
  /** Type guard used by option validation — unknown preset names fail loudly. */
13
13
  export declare function isPresetName(value: unknown): value is PresetName;
14
- /** Preset content: directory names (matched as dir-only `name/` patterns at any depth) and file names. */
14
+ /**
15
+ * Preset content: directory names (matched as dir-only `name/` patterns at any
16
+ * depth) and file names. A `dirs` entry MAY carry a leading slash (`/target`)
17
+ * — it then compiles to a scan-root-anchored pattern (`/target/`, plain
18
+ * gitignore anchoring) that matches only a same-named directory at the scan
19
+ * root itself, never nested ones; the named-negation exit key (`!target/`)
20
+ * un-excludes it like any other entry.
21
+ */
15
22
  export type Preset = {
16
23
  dirs: string[];
17
24
  files?: string[];
18
25
  };
19
26
  /**
20
27
  * The five preset groups. `dirs` entries compile to dir-only gitignore
21
- * patterns (`name/` — a plain file with the same name stays in scope);
22
- * `files` entries compile to bare names.
28
+ * patterns (`name/` — a plain file with the same name stays in scope; a
29
+ * leading-slash entry anchors to the scan root); `files` entries compile to
30
+ * bare names.
23
31
  */
24
32
  export declare const PRESETS: Record<PresetName, Preset>;
25
33
  /** The default mount set. */