@catheadowl/pathscope 0.1.0 → 0.2.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
@@ -1628,6 +1625,33 @@ function parentDirKey(key) {
1628
1625
  async function createExclusionEngine(rootKey, options = {}, io = nodeExclusionIO) {
1629
1626
  validateOptions(options);
1630
1627
  const respectGitignore = options.respectGitignore !== false;
1628
+ const asRule = (raw) => raw === "" || raw.startsWith("#") || raw === "!" ? null : raw;
1629
+ const ruleIg = (mounted) => {
1630
+ const ig = (0, import_ignore.default)();
1631
+ ig.add([mounted]);
1632
+ return ig;
1633
+ };
1634
+ const gitignoreRules = (lines, anchor, prefix) => {
1635
+ const out = [];
1636
+ for (const raw of lines) {
1637
+ const mounted = prefix === "" ? asRule(raw) : reanchorLine(raw, prefix);
1638
+ if (mounted === null) continue;
1639
+ out.push({ mounted, original: raw, source: "gitignore", gitignoreAnchor: anchor, ig: ruleIg(mounted) });
1640
+ }
1641
+ return out;
1642
+ };
1643
+ const channelHits = (rules, canonical) => {
1644
+ const hits = [];
1645
+ for (const r of rules) {
1646
+ const t = r.ig.test(canonical);
1647
+ if (!t.ignored && !t.unignored) continue;
1648
+ const hit = { source: r.source, ruleText: r.original };
1649
+ if (r.presetName !== void 0) hit.presetName = r.presetName;
1650
+ if (r.gitignoreAnchor !== void 0) hit.gitignoreAnchor = r.gitignoreAnchor;
1651
+ hits.push(hit);
1652
+ }
1653
+ return hits;
1654
+ };
1631
1655
  let top;
1632
1656
  if (respectGitignore) {
1633
1657
  let dir = rootKey;
@@ -1644,7 +1668,7 @@ async function createExclusionEngine(rootKey, options = {}, io = nodeExclusionIO
1644
1668
  dir = parent;
1645
1669
  }
1646
1670
  }
1647
- const inheritedLines = [];
1671
+ const inheritedRules = [];
1648
1672
  if (top !== void 0 && top !== rootKey) {
1649
1673
  const ancestors = [];
1650
1674
  let cur = parentDirKey(rootKey);
@@ -1654,38 +1678,73 @@ async function createExclusionEngine(rootKey, options = {}, io = nodeExclusionIO
1654
1678
  cur = parentDirKey(cur);
1655
1679
  }
1656
1680
  ancestors.reverse();
1657
- for (const ancestor of ancestors) {
1681
+ for (const [idx, ancestor] of ancestors.entries()) {
1682
+ const hops = ancestors.length - idx;
1683
+ const anchor = `inherited:${Array.from({ length: hops }, () => "..").join("/")}`;
1658
1684
  const text = await io.readGitignore(ancestor);
1659
- if (text !== null) inheritedLines.push(...splitLines(text));
1685
+ if (text === null) continue;
1686
+ for (const raw of splitLines(text)) {
1687
+ const mounted = asRule(raw);
1688
+ if (mounted === null) continue;
1689
+ inheritedRules.push({
1690
+ mounted,
1691
+ original: raw,
1692
+ source: "gitignore",
1693
+ gitignoreAnchor: anchor,
1694
+ ig: ruleIg(mounted)
1695
+ });
1696
+ }
1660
1697
  }
1661
1698
  }
1662
1699
  const rootPrefix = top !== void 0 && rootKey.startsWith(top) ? top : rootKey;
1663
1700
  const offRel = rootKey.slice(rootPrefix.length).replace(/^\//, "");
1664
1701
  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
- };
1702
+ const mountOne = (pattern) => offRel === "" ? pattern : reanchorLine(pattern, offRel);
1669
1703
  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);
1704
+ const coreRules = [];
1705
+ for (const pName of options.mountPresets ?? DEFAULT_MOUNTED_PRESETS) {
1706
+ const preset = PRESETS[pName];
1707
+ for (const dir of preset.dirs) {
1708
+ const mounted = mountOne(`${dir}/`);
1709
+ coreRules.push({ mounted, original: `${dir}/`, source: "preset", presetName: pName, ig: ruleIg(mounted) });
1710
+ }
1711
+ for (const file of preset.files ?? []) {
1712
+ const mounted = mountOne(file);
1713
+ coreRules.push({ mounted, original: file, source: "preset", presetName: pName, ig: ruleIg(mounted) });
1714
+ }
1715
+ }
1716
+ coreRules.push(...inheritedRules);
1673
1717
  const rootIgnoreText = respectGitignore ? await io.readGitignore(rootKey) : null;
1674
1718
  if (rootIgnoreText !== null) {
1675
- const lines = mount(splitLines(rootIgnoreText));
1676
- if (lines.length > 0) core.add(lines);
1719
+ coreRules.push(...gitignoreRules(splitLines(rootIgnoreText), "", offRel));
1677
1720
  }
1721
+ if (coreRules.length > 0) core.add(coreRules.map((r) => r.mounted));
1678
1722
  const policy = (0, import_ignore.default)();
1723
+ const policyRules = [];
1679
1724
  if (options.exclude !== void 0 && options.exclude.length > 0) {
1680
- policy.add(mount(options.exclude));
1725
+ for (const pattern of options.exclude) {
1726
+ const mounted = mountOne(pattern);
1727
+ policyRules.push({ mounted, original: pattern, source: "policy", ig: ruleIg(mounted) });
1728
+ }
1729
+ policy.add(policyRules.map((r) => r.mounted));
1681
1730
  }
1682
1731
  const overrideIg = (0, import_ignore.default)();
1732
+ const overrideRules = [];
1683
1733
  if (options.override !== void 0 && options.override.length > 0) {
1684
- overrideIg.add(mount(options.override));
1734
+ for (const pattern of options.override) {
1735
+ const mounted = mountOne(pattern);
1736
+ overrideRules.push({ mounted, original: pattern, source: "override", ig: ruleIg(mounted) });
1737
+ }
1738
+ overrideIg.add(overrideRules.map((r) => r.mounted));
1685
1739
  }
1686
1740
  const strictIg = (0, import_ignore.default)();
1741
+ const strictRules = [];
1687
1742
  if (options.strict !== void 0 && options.strict.length > 0) {
1688
- strictIg.add(mount(options.strict.map((rule) => rule.pattern)));
1743
+ for (const rule of options.strict) {
1744
+ const mounted = mountOne(rule.pattern);
1745
+ strictRules.push({ mounted, original: rule.pattern, source: "strict", ig: ruleIg(mounted) });
1746
+ }
1747
+ strictIg.add(strictRules.map((r) => r.mounted));
1689
1748
  }
1690
1749
  const configHomes = options.boundaryStones?.configHomes ?? [];
1691
1750
  const gitignoreProxy = options.boundaryStones?.gitignoreProxy === true;
@@ -1707,61 +1766,115 @@ async function createExclusionEngine(rootKey, options = {}, io = nodeExclusionIO
1707
1766
  };
1708
1767
  const exemptibleNames = gitignoreProxy ? /* @__PURE__ */ new Set([".git", ".gitignore"]) : /* @__PURE__ */ new Set([".git"]);
1709
1768
  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;
1769
+ const stoneDetail = (hit, relDir) => {
1770
+ if (hit == null || hit === false) return [];
1771
+ if (hit === true) return [{ enforced: true }];
1713
1772
  let names = hit;
1714
- if (isExemptDir(key.slice(rootKey.length + 1))) {
1773
+ if (isExemptDir(relDir)) {
1715
1774
  names = names.filter((name) => !exemptibleNames.has(name));
1716
1775
  }
1717
1776
  if (unenforcedNames !== null) {
1718
1777
  names = names.filter((name) => !unenforcedNames.has(name));
1719
1778
  }
1720
- return names.length > 0;
1779
+ const enforcedSet = new Set(names);
1780
+ return hit.map((name) => ({ stoneName: name, enforced: enforcedSet.has(name) }));
1721
1781
  };
1782
+ const stoneHitEntries = (detail) => detail.map((d) => {
1783
+ const hit = { source: "stone", enforced: d.enforced };
1784
+ if (d.stoneName !== void 0) hit.stoneName = d.stoneName;
1785
+ return hit;
1786
+ });
1722
1787
  const combinedExcludes = (canonical) => {
1723
1788
  const policyResult = policy.test(canonical);
1724
1789
  if (policyResult.ignored) return true;
1725
1790
  if (policyResult.unignored) return false;
1726
1791
  return core.test(canonical).ignored;
1727
1792
  };
1793
+ const adjudicateDirectoryImpl = (name, dirPath, stoneHit) => {
1794
+ const key = dirPath.replace(/\/+$/, "");
1795
+ const relDir = key === rootKey ? "" : key.slice(rootKey.length + 1);
1796
+ const hits = [];
1797
+ if (key !== rootKey) {
1798
+ const stones = stoneHitEntries(stoneDetail(stoneHit, relDir));
1799
+ hits.push(...stones);
1800
+ if (stones.some((h) => h.enforced)) return { excluded: true, hits };
1801
+ }
1802
+ const canonicalDir = toCanonical(`${relDir}/`);
1803
+ hits.push(...channelHits(strictRules, canonicalDir));
1804
+ if (strictIg.test(canonicalDir).ignored) return { excluded: true, hits };
1805
+ if (overrideIg.test(canonicalDir).ignored) {
1806
+ hits.push(...channelHits(overrideRules, canonicalDir));
1807
+ return { excluded: false, hits };
1808
+ }
1809
+ hits.push(...channelHits(coreRules, canonicalDir));
1810
+ hits.push(...channelHits(policyRules, canonicalDir));
1811
+ const policyResult = policy.test(canonicalDir);
1812
+ if (policyResult.ignored) return { excluded: true, hits };
1813
+ if (policyResult.unignored) {
1814
+ if (core.test(canonicalDir).ignored) {
1815
+ core.add(`!/${canonicalDir}`);
1816
+ }
1817
+ } else if (core.test(canonicalDir).ignored) {
1818
+ return { excluded: true, hits };
1819
+ }
1820
+ if (excludeDotEntries && name.startsWith(".")) {
1821
+ hits.push({ source: "dot" });
1822
+ return { excluded: true, hits };
1823
+ }
1824
+ return { excluded: false, hits };
1825
+ };
1826
+ const adjudicateFileImpl = (relPath) => {
1827
+ const canonical = toCanonical(relPath);
1828
+ const hits = [];
1829
+ hits.push(...channelHits(strictRules, canonical));
1830
+ if (strictIg.test(canonical).ignored) return { admitted: false, hits };
1831
+ if (overrideIg.test(canonical).ignored) {
1832
+ hits.push(...channelHits(overrideRules, canonical));
1833
+ return { admitted: true, hits };
1834
+ }
1835
+ hits.push(...channelHits(coreRules, canonical));
1836
+ hits.push(...channelHits(policyRules, canonical));
1837
+ if (combinedExcludes(canonical)) return { admitted: false, hits };
1838
+ if (excludeDotEntries && baseNamePosix(relPath).startsWith(".")) {
1839
+ hits.push({ source: "dot" });
1840
+ return { admitted: false, hits };
1841
+ }
1842
+ return { admitted: true, hits };
1843
+ };
1728
1844
  return {
1729
1845
  rootKey,
1730
1846
  stoneNames,
1731
1847
  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;
1848
+ return adjudicateDirectoryImpl(name, dirPath, stoneHit).excluded;
1749
1849
  },
1750
1850
  foldGitignore(dirPath, text) {
1751
1851
  if (text == null || !respectGitignore) return;
1752
1852
  const key = dirPath.replace(/\/+$/, "");
1753
1853
  if (key === rootKey) return;
1754
1854
  const relDir = key.slice(rootKey.length + 1);
1755
- const lines = mount(splitLines(text), relDir);
1756
- if (lines.length > 0) core.add(lines);
1855
+ const rules = gitignoreRules(splitLines(text), relDir, joinPosix(offRel, relDir));
1856
+ if (rules.length > 0) {
1857
+ core.add(rules.map((r) => r.mounted));
1858
+ coreRules.push(...rules);
1859
+ }
1757
1860
  },
1758
1861
  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;
1862
+ return adjudicateFileImpl(relPath).admitted;
1863
+ },
1864
+ adjudicateDirectory(name, dirPath, stoneHit) {
1865
+ return adjudicateDirectoryImpl(name, dirPath, stoneHit);
1866
+ },
1867
+ adjudicateFile(relPath) {
1868
+ return adjudicateFileImpl(relPath);
1869
+ },
1870
+ attributeStones(relDir, stoneHit) {
1871
+ if (relDir === "") return [];
1872
+ return stoneHitEntries(stoneDetail(stoneHit, relDir));
1873
+ },
1874
+ adjudicateStrict(relPath, isDir) {
1875
+ const trimmed = relPath.replace(/\/+$/, "");
1876
+ const canonical = toCanonical(isDir ? `${trimmed}/` : trimmed);
1877
+ return { hit: strictIg.test(canonical).ignored, hits: channelHits(strictRules, canonical) };
1765
1878
  }
1766
1879
  };
1767
1880
  }
@@ -1825,9 +1938,117 @@ async function walkScope(root, options = {}) {
1825
1938
  return { files: [...files].sort(), diagnostics };
1826
1939
  }
1827
1940
 
1941
+ // src/explain.ts
1942
+ var import_node_fs4 = require("node:fs");
1943
+ var import_node_path3 = require("node:path");
1944
+ function parseRelPath(relPath) {
1945
+ if (typeof relPath !== "string") {
1946
+ throw new PathscopeConfigError("relPath must be a scan-root-relative POSIX path string");
1947
+ }
1948
+ if (relPath.includes("\\")) {
1949
+ throw new PathscopeConfigError(`relPath "${relPath}" contains a backslash \u2014 pass POSIX-separator form`);
1950
+ }
1951
+ if (relPath.startsWith("/")) {
1952
+ throw new PathscopeConfigError(`relPath "${relPath}" is absolute \u2014 pass a scan-root-RELATIVE path`);
1953
+ }
1954
+ const isDir = relPath.endsWith("/");
1955
+ let core = relPath;
1956
+ while (core.startsWith("./")) core = core.slice(2);
1957
+ if (core === "." || core === "") return { segments: [], isDir: true, isRoot: true };
1958
+ const segments = core.replace(/\/+$/, "").split("/");
1959
+ for (const seg of segments) {
1960
+ if (seg === "") {
1961
+ throw new PathscopeConfigError(`relPath "${relPath}" has an empty segment (double slash)`);
1962
+ }
1963
+ if (seg === "." || seg === "..") {
1964
+ throw new PathscopeConfigError(`relPath "${relPath}" escapes the scan root (".", ".." segments)`);
1965
+ }
1966
+ }
1967
+ return { segments, isDir, isRoot: false };
1968
+ }
1969
+ async function explainScopePath(root, relPath, options = {}) {
1970
+ const { segments, isDir, isRoot } = parseRelPath(relPath);
1971
+ const rootNative = (0, import_node_path3.resolve)(root);
1972
+ if (!(0, import_node_fs4.existsSync)(rootNative)) {
1973
+ throw new PathscopeConfigError(`scan root does not exist: ${rootNative}`);
1974
+ }
1975
+ const baseKey = rootNative.replace(/\\/g, "/").replace(/\/+$/, "");
1976
+ const engine = await createExclusionEngine(baseKey, options);
1977
+ const io = nodeExclusionIO;
1978
+ const probeStones = async (dirKey) => {
1979
+ const hits = [];
1980
+ for (const name of engine.stoneNames) {
1981
+ if (await io.exists(dirKey, name)) hits.push(name);
1982
+ }
1983
+ return hits;
1984
+ };
1985
+ const withPath = (hits, path3) => hits.map((h) => ({ ...h, path: path3 }));
1986
+ if (isRoot) {
1987
+ return { excluded: false, structural: false, hitChain: [], explicit: { pierceable: true, blockers: [] } };
1988
+ }
1989
+ const hitChain = [];
1990
+ const blockers = [];
1991
+ const keys = [];
1992
+ let key = baseKey;
1993
+ for (const seg of segments) {
1994
+ key = `${key}/${seg}`;
1995
+ keys.push(key);
1996
+ }
1997
+ let excluded;
1998
+ let structural = false;
1999
+ let stoppedDepth = -1;
2000
+ for (let i = 0; i < segments.length; i++) {
2001
+ const name = segments[i];
2002
+ const relHere = segments.slice(0, i + 1).join("/");
2003
+ const isLeaf = i === segments.length - 1;
2004
+ const adjudicateAsDir = isLeaf ? isDir : true;
2005
+ if (adjudicateAsDir) {
2006
+ const stoneHit = await probeStones(keys[i]);
2007
+ const adj = engine.adjudicateDirectory(name, keys[i], stoneHit);
2008
+ hitChain.push(...withPath(adj.hits, relHere));
2009
+ if (adj.excluded) {
2010
+ excluded = true;
2011
+ structural = true;
2012
+ stoppedDepth = i;
2013
+ break;
2014
+ }
2015
+ engine.foldGitignore(keys[i], await io.readGitignore(keys[i]));
2016
+ if (isLeaf) excluded = false;
2017
+ } else {
2018
+ const adj = engine.adjudicateFile(relHere);
2019
+ hitChain.push(...withPath(adj.hits, relHere));
2020
+ excluded = !adj.admitted;
2021
+ }
2022
+ }
2023
+ for (const hit of hitChain) {
2024
+ if (hit.source === "strict" || hit.source === "stone" && hit.enforced !== false) {
2025
+ blockers.push(hit);
2026
+ }
2027
+ }
2028
+ if (stoppedDepth >= 0 && stoppedDepth < segments.length - 1) {
2029
+ for (let j = stoppedDepth + 1; j < segments.length; j++) {
2030
+ const relHere = segments.slice(0, j + 1).join("/");
2031
+ const isLeaf = j === segments.length - 1;
2032
+ const asDir = isLeaf ? isDir : true;
2033
+ if (asDir) {
2034
+ blockers.push(...withPath(engine.attributeStones(relHere, await probeStones(keys[j])), relHere));
2035
+ blockers.push(...withPath(engine.adjudicateStrict(relHere, true).hits, relHere));
2036
+ } else {
2037
+ blockers.push(...withPath(engine.adjudicateStrict(relHere, false).hits, relHere));
2038
+ }
2039
+ }
2040
+ }
2041
+ return {
2042
+ excluded: excluded ?? false,
2043
+ structural,
2044
+ hitChain,
2045
+ explicit: { pierceable: blockers.length === 0, blockers }
2046
+ };
2047
+ }
2048
+
1828
2049
  // src/universe.ts
1829
2050
  var import_node_child_process = require("node:child_process");
1830
- var import_node_path3 = require("node:path");
2051
+ var import_node_path4 = require("node:path");
1831
2052
  var import_ignore2 = __toESM(require_ignore(), 1);
1832
2053
  var repoRootCache = /* @__PURE__ */ new Map();
1833
2054
  function clearUniverseCache() {
@@ -1900,8 +2121,8 @@ function filterDiffRawRecords(stdout) {
1900
2121
  return [...kept];
1901
2122
  }
1902
2123
  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;
2124
+ const rel = (0, import_node_path4.relative)(rootAbs, (0, import_node_path4.join)(repoRootNative, repoRelPosix));
2125
+ if (rel === "" || (0, import_node_path4.isAbsolute)(rel) || rel.startsWith("..")) return null;
1905
2126
  return toPosix(rel);
1906
2127
  }
1907
2128
  function validateFilter(filter) {
@@ -1935,7 +2156,7 @@ async function gitUniverse(root, options = {}) {
1935
2156
  );
1936
2157
  }
1937
2158
  if (options.filter !== void 0) validateFilter(options.filter);
1938
- const rootAbs = (0, import_node_path3.resolve)(root);
2159
+ const rootAbs = (0, import_node_path4.resolve)(root);
1939
2160
  const repoRoot = repoRootOf(rootAbs);
1940
2161
  let repoRelative;
1941
2162
  if (variant === "staged") {
@@ -1961,15 +2182,15 @@ async function gitUniverse(root, options = {}) {
1961
2182
  }
1962
2183
 
1963
2184
  // src/discover.ts
1964
- var import_node_path6 = require("node:path");
2185
+ var import_node_path7 = require("node:path");
1965
2186
 
1966
2187
  // node_modules/.pnpm/find-up@8.0.0/node_modules/find-up/index.js
1967
- var import_node_path5 = __toESM(require("node:path"), 1);
2188
+ var import_node_path6 = __toESM(require("node:path"), 1);
1968
2189
 
1969
2190
  // node_modules/.pnpm/locate-path@8.0.0/node_modules/locate-path/index.js
1970
2191
  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);
2192
+ var import_node_path5 = __toESM(require("node:path"), 1);
2193
+ var import_node_fs5 = __toESM(require("node:fs"), 1);
1973
2194
  var import_node_url = require("node:url");
1974
2195
  var typeMappings = {
1975
2196
  directory: "isDirectory",
@@ -1990,10 +2211,10 @@ function locatePathSync(paths, {
1990
2211
  } = {}) {
1991
2212
  checkType(type);
1992
2213
  cwd = toPath(cwd);
1993
- const statFunction = allowSymlinks ? import_node_fs4.default.statSync : import_node_fs4.default.lstatSync;
2214
+ const statFunction = allowSymlinks ? import_node_fs5.default.statSync : import_node_fs5.default.lstatSync;
1994
2215
  for (const path_ of paths) {
1995
2216
  try {
1996
- const stat = statFunction(import_node_path4.default.resolve(cwd, path_), {
2217
+ const stat = statFunction(import_node_path5.default.resolve(cwd, path_), {
1997
2218
  throwIfNoEntry: false
1998
2219
  });
1999
2220
  if (!stat) {
@@ -2020,9 +2241,9 @@ var TEN_MEGABYTES_IN_BYTES = 10 * 1024 * 1024;
2020
2241
  // node_modules/.pnpm/find-up@8.0.0/node_modules/find-up/index.js
2021
2242
  var findUpStop = /* @__PURE__ */ Symbol("findUpStop");
2022
2243
  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);
2244
+ let directory = import_node_path6.default.resolve(toPath2(options.cwd) ?? "");
2245
+ const { root } = import_node_path6.default.parse(directory);
2246
+ const stopAt = import_node_path6.default.resolve(directory, toPath2(options.stopAt) ?? root);
2026
2247
  const limit = options.limit ?? Number.POSITIVE_INFINITY;
2027
2248
  const paths = [name].flat();
2028
2249
  const runMatcher = (locateOptions) => {
@@ -2042,12 +2263,12 @@ function findUpMultipleSync(name, options = {}) {
2042
2263
  break;
2043
2264
  }
2044
2265
  if (foundPath) {
2045
- matches.push(import_node_path5.default.resolve(directory, foundPath));
2266
+ matches.push(import_node_path6.default.resolve(directory, foundPath));
2046
2267
  }
2047
2268
  if (directory === stopAt || matches.length >= limit) {
2048
2269
  break;
2049
2270
  }
2050
- directory = import_node_path5.default.dirname(directory);
2271
+ directory = import_node_path6.default.dirname(directory);
2051
2272
  }
2052
2273
  return matches;
2053
2274
  }
@@ -2083,7 +2304,7 @@ function locateNearest(names, options = {}) {
2083
2304
  (name) => foundPosix.length >= suffixOf(name).length && fold(foundPosix.slice(foundPosix.length - suffixOf(name).length)) === fold(suffixOf(name))
2084
2305
  );
2085
2306
  if (hit === void 0) {
2086
- return { name: (0, import_node_path6.basename)(found), path: found };
2307
+ return { name: (0, import_node_path7.basename)(found), path: found };
2087
2308
  }
2088
2309
  return { name: hit, path: found };
2089
2310
  }
@@ -2095,6 +2316,7 @@ function locateNearest(names, options = {}) {
2095
2316
  PathscopeGitError,
2096
2317
  clearUniverseCache,
2097
2318
  createExclusionEngine,
2319
+ explainScopePath,
2098
2320
  gitUniverse,
2099
2321
  locateNearest,
2100
2322
  nodeExclusionIO,
@@ -206,8 +206,8 @@ export interface UniverseResult {
206
206
  /** Repository root as git reports it (`rev-parse --show-toplevel`). */
207
207
  repoRoot: string;
208
208
  /**
209
- * Diagnostics; always empty in 0.1.0 (the universe has no budget — git is
210
- * the authority, not a traversal that could be cut). The field exists for
209
+ * Diagnostics; always empty (the universe has no budget — git is the
210
+ * authority, not a traversal that could be cut). The field exists for
211
211
  * shape parity with {@link WalkResult}.
212
212
  */
213
213
  diagnostics: ScanDiagnostic[];
@@ -1,4 +1,35 @@
1
- import { type ScopeOptions } from './types.ts';
1
+ import { type PresetName, type ScopeOptions } from './types.ts';
2
+ /** The provenance layers of the exclusion stack, in full-stack priority order. */
3
+ export type HitSource = 'stone' | 'strict' | 'override' | 'preset' | 'gitignore' | 'policy' | 'dot';
4
+ /**
5
+ * One attribution entry of a layer adjudication (the read-only probe face's
6
+ * unit). Field payload by source: `stone` → stoneName + enforced
7
+ * (report-not-cut facts — a hit that does not execute its cut carries
8
+ * `enforced: false`); `strict`/`override`/`policy` → ruleText (the pattern
9
+ * as supplied); `preset` → presetName + ruleText (the entry as mounted);
10
+ * `gitignore` → gitignoreAnchor ('' = the scan root's own layer, a relative
11
+ * dir = a nested layer, 'inherited:..' = a layer above the scan root) +
12
+ * ruleText (the line as written — re-anchoring stays internal); `dot` →
13
+ * nothing beyond the source.
14
+ */
15
+ export interface LayerHit {
16
+ source: HitSource;
17
+ presetName?: PresetName;
18
+ gitignoreAnchor?: string;
19
+ ruleText?: string;
20
+ stoneName?: string;
21
+ enforced?: boolean;
22
+ }
23
+ /** Directory adjudication with attribution — `excluded` is the walk verdict verbatim. */
24
+ export interface DirectoryAdjudication {
25
+ excluded: boolean;
26
+ hits: LayerHit[];
27
+ }
28
+ /** File adjudication with attribution — `admitted` is the walk verdict verbatim. */
29
+ export interface FileAdjudication {
30
+ admitted: boolean;
31
+ hits: LayerHit[];
32
+ }
2
33
  /**
3
34
  * Filesystem access for the engine's construction-time inherited phase.
4
35
  * Methods receive POSIX-separator absolute directory keys —
@@ -65,6 +96,45 @@ export interface ExclusionEngine {
65
96
  * budget is a chassis concern owned by walkScope.
66
97
  */
67
98
  admitFile(relPath: string): boolean;
99
+ /**
100
+ * {@link ExclusionEngine.excludeDirectory} with attribution: the same
101
+ * verdict (and the same policy-negation restatement side effect), plus the
102
+ * per-layer hit list in full-stack priority order — the read-only probe
103
+ * face's engine side. Every layer that MATCHED reports an entry
104
+ * (non-matching layers stay silent); within the combined table the entries
105
+ * follow the rule stream (presets → cascade → folds → policy rear seat),
106
+ * so the last table entry is the last-match-wins winner. The verdict comes
107
+ * from the same rule instances the walk uses — identical by construction.
108
+ */
109
+ adjudicateDirectory(name: string, dirPath: string, stoneHit?: boolean | readonly string[]): DirectoryAdjudication;
110
+ /**
111
+ * {@link ExclusionEngine.admitFile} with attribution — same file-order
112
+ * verdict plus the per-layer hit list (see
113
+ * {@link ExclusionEngine.adjudicateDirectory}).
114
+ */
115
+ adjudicateFile(relPath: string): FileAdjudication;
116
+ /**
117
+ * Stone attribution only (pure): per-stone hit entries with `enforced`
118
+ * flags for one scan-root-relative directory — the exemption (named
119
+ * subtree) and the alignment face (report-not-cut) are applied exactly as
120
+ * the truncation adjudication applies them. The scan root itself never
121
+ * truncates, so `relDir: ''` reports nothing (the universe-boundary
122
+ * guard). The probe's explicit projection uses this under pruned
123
+ * subtrees, where rule adjudication must NOT run but stone facts remain
124
+ * consumer-relevant.
125
+ */
126
+ attributeStones(relDir: string, stoneHit: readonly string[]): LayerHit[];
127
+ /**
128
+ * Strict-channel adjudication only (pure): whether the strict immune
129
+ * channel hits a scan-root-relative path, with per-rule attribution.
130
+ * `isDir` selects the directory form (trailing-slash canonical space) of
131
+ * the path. The projection face for pruned-subtree walks — strict is the
132
+ * one rule channel explicit naming can never pierce.
133
+ */
134
+ adjudicateStrict(relPath: string, isDir: boolean): {
135
+ hit: boolean;
136
+ hits: LayerHit[];
137
+ };
68
138
  }
69
139
  /** Validate options; malformed configuration fails loudly instead of scanning differently. */
70
140
  export declare function validateOptions(options: ScopeOptions): void;