@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/CHANGELOG.md +135 -90
- package/README.md +40 -1
- package/dist/cascade.d.ts +6 -0
- package/dist/cascade.js +21 -11
- package/dist/cascade.js.map +1 -1
- package/dist/cjs/cascade.d.ts +6 -0
- package/dist/cjs/exclusion-engine.d.ts +71 -1
- package/dist/cjs/explain.d.ts +109 -0
- package/dist/cjs/index.d.ts +10 -6
- package/dist/cjs/index.js +295 -73
- package/dist/cjs/types.d.ts +2 -2
- package/dist/exclusion-engine.d.ts +71 -1
- package/dist/exclusion-engine.js +234 -93
- package/dist/exclusion-engine.js.map +1 -1
- package/dist/explain.d.ts +109 -0
- package/dist/explain.js +193 -0
- package/dist/explain.js.map +1 -0
- package/dist/index.d.ts +10 -6
- package/dist/index.js +8 -5
- package/dist/index.js.map +1 -1
- package/dist/types.d.ts +2 -2
- package/docs/glossary.md +27 -3
- package/docs/semantics.md +11 -1
- package/package.json +7 -4
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
|
|
1441
|
-
|
|
1442
|
-
|
|
1443
|
-
|
|
1444
|
-
|
|
1445
|
-
|
|
1446
|
-
|
|
1447
|
-
|
|
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
|
|
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
|
|
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
|
|
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
|
|
1671
|
-
|
|
1672
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
1711
|
-
if (hit ===
|
|
1712
|
-
if (hit
|
|
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(
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
1756
|
-
if (
|
|
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
|
-
|
|
1760
|
-
|
|
1761
|
-
|
|
1762
|
-
|
|
1763
|
-
|
|
1764
|
-
|
|
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
|
|
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,
|
|
1904
|
-
if (rel === "" || (0,
|
|
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,
|
|
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
|
|
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
|
|
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
|
|
1972
|
-
var
|
|
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 ?
|
|
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(
|
|
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 =
|
|
2024
|
-
const { root } =
|
|
2025
|
-
const stopAt =
|
|
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(
|
|
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 =
|
|
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,
|
|
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,
|
package/dist/cjs/types.d.ts
CHANGED
|
@@ -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
|
|
210
|
-
*
|
|
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;
|