projectkeeper 0.0.0-stage → 1.0.0

package/src/scope/ignore.ts

@@ -0,0 +1,126 @@
+/**
+ * The project's own ignore rules, as git itself judges them (Spec §1.1; CKC-04 AC-17): what git leaves out
+ * (`git ls-files --others --ignored --exclude-standard --directory`) and the rule that does it — which ignore file,
+ * which line, which pattern (`git check-ignore -v`). A directory without version control has no ignore rules; a
+ * `.gitignore` there is just a file.
+ *
+ * Read-only: every call goes through `git()` (no optional locks, so not even the index's timestamps are refreshed).
+ */
+import { git } from '../util/git.ts';
+import { nameForm } from '../util/paths.ts';
+
+export interface IgnoreRule {
+  readonly file: string;
+  readonly line: number;
+  readonly pattern: string;
+}
+export interface IgnoredEntry {
+  /** Relative to the root the listing ran in, forward slashes, no trailing slash. */
+  readonly rel: string;
+  readonly dir: boolean;
+  readonly rule: IgnoreRule | null;
+}
+
+const LONG = 60_000;
+
+/** Paths git leaves out under `root`, whole directories collapsed; null when `root` is not in a git work tree. */
+function listIgnored(root: string): string[] | null {
+  const r = git(root, ['ls-files', '--others', '--ignored', '--exclude-standard', '--directory', '-z'], LONG);
+  if (!r.ok) return null;
+  return r.out.split('\0').filter(Boolean);
+}
+
+/** `"a\tb"` → a<TAB>b: git quotes a path with control characters, quotes or backslashes even with quotePath off. */
+function unquote(path: string): string {
+  if (!(path.startsWith('"') && path.endsWith('"'))) return path;
+  const body = path.slice(1, -1);
+  const bytes: number[] = [];
+  for (let i = 0; i < body.length; i += 1) {
+    const c = body[i]!;
+    if (c !== '\\') { bytes.push(...Buffer.from(c, 'utf8')); continue; }
+    const n = body[i + 1] ?? '';
+    if (/[0-7]/.test(n)) { bytes.push(parseInt(body.slice(i + 1, i + 4), 8)); i += 3; continue; }
+    bytes.push(({ t: 9, n: 10, r: 13, '"': 34, '\\': 92, a: 7, b: 8, f: 12, v: 11 } as Record<string, number>)[n] ?? n.charCodeAt(0));
+    i += 1;
+  }
+  return Buffer.from(bytes).toString('utf8');
+}
+
+/** The rule that leaves each path out, from `git check-ignore -v`. Paths are passed in batches to stay within the command line. */
+export function ignoreRules(root: string, paths: readonly string[]): Map<string, IgnoreRule> {
+  const out = new Map<string, IgnoreRule>();
+  let batch: string[] = [];
+  let size = 0;
+  const flush = () => {
+    if (batch.length === 0) return;
+    const r = git(root, ['-c', 'core.quotePath=false', 'check-ignore', '-v', '--', ...batch], LONG);
+    for (const line of r.out.split(/\r?\n/)) {
+      const m = /^(.+?):(\d+):(.*)\t(.+)$/.exec(line);
+      if (!m || m[3]!.startsWith('!')) continue;   // a negated pattern keeps the path in
+      out.set(unquote(m[4]!).replace(/\/$/, ''), { file: m[1]!, line: Number(m[2]), pattern: m[3]! });
+    }
+    batch = [];
+    size = 0;
+  };
+  for (const p of paths) {
+    batch.push(p);
+    size += p.length + 3;
+    if (batch.length >= 200 || size > 6000) flush();
+  }
+  flush();
+  return out;
+}
+
+/**
+ * What the ignore rules leave out under `root`, each with its rule; null without version control. A directory git lists
+ * because every file in it is ignored (no pattern names the directory itself) takes the rule of its files.
+ */
+export function ignoredEntries(root: string): IgnoredEntry[] | null {
+  const listed = listIgnored(root);
+  if (listed === null) return null;
+  const dirs = listed.filter((p) => p.endsWith('/')).map((p) => p.slice(0, -1));
+  const inDir = (f: string) => dirs.some((d) => f.startsWith(`${d}/`));
+  const files = listed.filter((p) => !p.endsWith('/'));
+  const scattered = files.filter((f) => !inDir(f));
+  const rules = ignoreRules(root, [...dirs.map((d) => `${d}/`), ...scattered]);
+  const missing = dirs.filter((d) => !rules.has(d));
+  const byFile = missing.length ? ignoreRules(root, files.filter((f) => missing.some((d) => f.startsWith(`${d}/`)))) : new Map<string, IgnoreRule>();
+  return [
+    ...dirs.map((d) => ({ rel: d, dir: true, rule: rules.get(d) ?? [...byFile].find(([f]) => f.startsWith(`${d}/`))?.[1] ?? null })),
+    ...scattered.map((f) => ({ rel: f, dir: false, rule: rules.get(f) ?? null })),
+  ];
+}
+
+/**
+ * A predicate for a walk under `root`: is this relative path (forward slashes) left out by the ignore rules? Null
+ * without version control.
+ */
+export function ignoredPredicate(root: string): ((rel: string) => boolean) | null {
+  const listed = listIgnored(root);
+  if (listed === null) return null;
+  return predicateOf(listed.filter((p) => p.endsWith('/')).map((p) => p.slice(0, -1)), listed.filter((p) => !p.endsWith('/')));
+}
+
+/** The same predicate from entries already listed. */
+export function predicateFrom(entries: readonly IgnoredEntry[]): (rel: string) => boolean {
+  return predicateOf(entries.filter((e) => e.dir).map((e) => e.rel), entries.filter((e) => !e.dir).map((e) => e.rel));
+}
+
+function predicateOf(dirList: readonly string[], fileList: readonly string[]): (rel: string) => boolean {
+  // Both sides in the form names are kept in: what git lists and what a walk asks about are compared, nothing more.
+  const dirs = new Set(dirList.map((d) => nameForm(d)));
+  const files = new Set(fileList.map((f) => nameForm(f)));
+  return (rel: string) => {
+    const p = nameForm(rel).split('\\').join('/');
+    if (files.has(p) || dirs.has(p)) return true;
+    const segs = p.split('/');
+    for (let i = 1; i < segs.length; i += 1) if (dirs.has(segs.slice(0, i).join('/'))) return true;
+    return false;
+  };
+}
+
+/** One path, asked of git directly (the watcher's check for a file it has not seen). */
+export function isIgnored(root: string, rel: string): boolean {
+  const r = git(root, ['check-ignore', '-q', '--', rel.split('\\').join('/')]);
+  return r.ok;
+}

package/src/scope/ignored-place.ts

@@ -0,0 +1,93 @@
+/**
+ * A location that lies in a place the project's own ignore rules leave out (Spec §1.1, D105; CKC-04 AC-17, CKC-07
+ * AC-10): the usual case is a worker's worktree under an ignored directory (`.worktrees/K-cq` in a repository whose
+ * `.gitignore` says `.worktrees/`). Its working files are not pending material — a change in them is not listed, starts
+ * no round and is in no Follow up — while its branch and commits still reach the ledger from version control, and its
+ * commits the trunk does not have still wait like any commit.
+ *
+ * The scan and the watcher already ask a location's own repository about each file (./ignore.ts); what they did not ask
+ * is whether the location itself sits where a repository around it ignores. That is asked here, of git, for every
+ * repository in scope that holds the location, nested ones included — outward until a repository of its own is reached:
+ * a nested repository belongs by its own history (§1.1), so the rules of the one around it stop at it, and a nested
+ * repository the outer one ignores (`/app/`) is still read. Not left out: what the owner took in, what the Keeper judged
+ * the project's material (`overridesIgnoreRules`), and a place kept for recovery only (read as history, D82).
+ *
+ * Read-only: `git check-ignore` through `git()`.
+ */
+import type { ScopeItem } from '../model/types.ts';
+import { isWithin, pathKey, relativeDisplay } from '../util/paths.ts';
+import { ignoreRules, type IgnoreRule } from './ignore.ts';
+import { overridesIgnoreRules, treatmentOf } from './skip.ts';
+
+export interface IgnoredPlace {
+  /** The rule that leaves the location out. */
+  readonly rule: IgnoreRule;
+  /** The scope item whose repository the rule belongs to. */
+  readonly by: ScopeItem;
+}
+
+/** What git said about a location, kept a short while: the watcher asks for every file event, the coverage at every pass. */
+const asked = new Map<string, { at: number; rule: IgnoreRule | null }>();
+const KEEP_MS = 20_000;
+
+/** Forget what git said (a test that changes an ignore file within the keep time). */
+export function forgetIgnoredPlaces(): void { asked.clear(); }
+
+function ruleFor(root: string, rel: string, now: number): IgnoreRule | null {
+  const key = `${pathKey(root)}\n${rel}`;
+  const had = asked.get(key);
+  if (had && now - had.at < KEEP_MS) return had.rule;
+  const rule = ignoreRules(root, [rel]).get(rel) ?? null;
+  asked.set(key, { at: now, rule });
+  return rule;
+}
+
+const locational = (scope: readonly ScopeItem[]) => scope.filter((i) => i.category !== 'Session source');
+
+/** Its own choice to take in what the rules leave out, or a place read as history: the rules around it do not apply. */
+const standsApart = (scope: readonly ScopeItem[], item: ScopeItem) => overridesIgnoreRules(scope, item) || treatmentOf(item) === 'history';
+
+/**
+ * The ignore rule of a repository in scope that leaves this item's own location out, or null. A repository of its own is
+ * never left out this way; the walk outward stops at the first repository, and at an item the owner took in.
+ */
+export function ignoredPlaceOf(scope: readonly ScopeItem[], item: ScopeItem, now = Date.now()): IgnoredPlace | null {
+  if (item.category === 'Session source' || item.category === 'Repository' || standsApart(scope, item)) return null;
+  const around = locational(scope)
+    .filter((o) => o !== item && !o.missing && o.path.length < item.path.length && isWithin(o.path, item.path))
+    .sort((a, b) => b.path.length - a.path.length);
+  for (const o of around) {
+    if (standsApart(scope, o)) return null;
+    if (o.versionControl !== 'none') {
+      const rule = ruleFor(o.path, relativeDisplay(o.path, item.path), now);
+      if (rule) return { rule, by: o };
+    }
+    if (o.category === 'Repository') return null;
+  }
+  return null;
+}
+
+/**
+ * For many paths at once (the coverage's list of what waits): the ignored place a file lies in, or null. Each scope item
+ * is asked about once.
+ */
+export function ignoredPlaceLookup(scope: readonly ScopeItem[]): (path: string) => IgnoredPlace | null {
+  const deepestFirst = locational(scope).sort((a, b) => b.path.length - a.path.length);
+  // Only an item that is no repository of its own, inside another location, can lie in an ignored place.
+  const candidates = deepestFirst.filter((i) => i.category !== 'Repository' && deepestFirst.some((o) => o !== i && o.path.length < i.path.length && isWithin(o.path, i.path)));
+  if (candidates.length === 0) return () => null;
+  const byItem = new Map<string, IgnoredPlace | null>();
+  const now = Date.now();
+  return (path: string) => {
+    const item = deepestFirst.find((i) => isWithin(i.path, path));
+    if (!item || !candidates.includes(item)) return null;
+    let place = byItem.get(item.id);
+    if (place === undefined) { place = ignoredPlaceOf(scope, item, now); byItem.set(item.id, place); }
+    return place;
+  };
+}
+
+/** `.gitignore line 2: .worktrees/` — the rule as the scope list names it. */
+export function ruleText(rule: IgnoreRule): string {
+  return `${rule.file} line ${rule.line}: ${rule.pattern}`;
+}

package/src/scope/skip.ts

@@ -0,0 +1,161 @@
+/**
+ * The one skip list (Spec §1.1; CKC-04 AC-13, AC-17): which directories are never walked as project material, which
+ * names are build output, caches or installed dependencies, which directories projects keep vendored code in, which
+ * files are documents, and what a scope item's relation means for what is read from it. Scope discovery, the file
+ * scan and the watcher read all of it from here; the organizing code should too (takeover.ts and materials.ts still
+ * keep their own path patterns and move here when their owner next touches them).
+ *
+ * A name here is a candidate, not a verdict: discovery lists what it finds with the reason, the Keeper judges it
+ * (`pk_classify_scope`) and the owner can correct it. The project's own ignore rules are in ./ignore.ts; git decides
+ * those, not this list.
+ */
+import { extname } from 'node:path';
+import type { ScopeItem } from '../model/types.ts';
+import type { UsedAs } from '../model/vocab.ts';
+import { isWithin } from '../util/paths.ts';
+
+/** Version-control internals, and the usual home of worktrees (each registered worktree is measured on its own). */
+export const NEVER_WALKED: ReadonlySet<string> = new Set(['.git', '.hg', '.svn', '.worktrees']);
+
+/** Usual names of what a build or a tool writes, with the kind shown as the reason. Compared without regard to case. */
+const GENERATED: Readonly<Record<string, string>> = {
+  build: 'build output', dist: 'build output', out: 'build output', target: 'build output', deriveddata: 'build output',
+  cmakefiles: 'build output', '.eggs': 'build output',
+  '.gradle': 'build cache', '.next': 'build cache', '.nuxt': 'build cache', '.svelte-kit': 'build cache',
+  '.angular': 'build cache', '.turbo': 'build cache', '.parcel-cache': 'build cache', '.cache': 'cache', '__pycache__': 'cache',
+  '.pytest_cache': 'cache', '.mypy_cache': 'cache', '.ruff_cache': 'cache', '.tox': 'cache', coverage: 'test coverage output',
+  '.nyc_output': 'test coverage output', '.playwright-cli': 'tool output',
+};
+/** Where package managers install other people's code. Not distributed with the project; nothing in it is read. */
+const DEPENDENCIES: ReadonlySet<string> = new Set(['node_modules', 'bower_components', 'jspm_packages', '.venv', 'venv', 'site-packages']);
+/** Usual names of directories a project keeps vendored third-party code in; their documents are read as Reference only. */
+const VENDORED: ReadonlySet<string> = new Set(['third_party', 'third-party', 'thirdparty', 'vendor', 'vendors', 'external', 'externals', 'extern']);
+
+/** Third-party material of these kinds is not read at all: installed dependencies, and links to places outside the project. */
+export const NOT_READ_KINDS: ReadonlySet<string> = new Set(['installed dependencies', 'linked in']);
+
+export interface NameClass {
+  readonly relation: 'Generated' | 'Third-party material';
+  readonly kind: string;
+  readonly evidence: string;
+}
+
+/** What a directory's name alone suggests, or null. */
+export function classifyName(name: string): NameClass | null {
+  const n = name.toLowerCase();
+  if (GENERATED[n]) return { relation: 'Generated', kind: GENERATED[n]!, evidence: `${name}/ is a usual name for ${GENERATED[n]}` };
+  if (DEPENDENCIES.has(n)) return { relation: 'Third-party material', kind: 'installed dependencies', evidence: `${name}/ is where a package manager installs dependencies` };
+  if (VENDORED.has(n)) return { relation: 'Third-party material', kind: 'vendored code', evidence: `${name}/ is a usual name for vendored third-party code` };
+  return null;
+}
+
+/** A walk that has no scope item telling it otherwise does not enter these: version control, build output, dependencies, vendored code. */
+export function isSkippedName(name: string): boolean {
+  return NEVER_WALKED.has(name.toLowerCase()) || classifyName(name) !== null;
+}
+
+/** A directory of vendored code holds libraries worth telling apart (each with its own upstream and license). */
+export function isVendoredName(name: string): boolean {
+  return VENDORED.has(name.toLowerCase());
+}
+
+/**
+ * Whether an item takes in what the project's ignore rules leave out: the owner chose to include it (an answer to the
+ * scope question, a correction, or a location added by hand inside the project), or the Keeper judged it the project's
+ * material. The project's own locations are not such a choice: the rules apply inside them.
+ */
+export function overridesIgnoreRules(scope: readonly ScopeItem[], item: ScopeItem): boolean {
+  if (item.relation === 'Excluded') return false;
+  if (item.ignoredBy != null || (item.classification != null && item.classification.by !== 'program')) return true;
+  return item.addedBy === 'owner' && scope.some((o) => o !== item && o.category !== 'Session source' && o.path.length < item.path.length && isWithin(o.path, item.path));
+}
+
+/** The first segment of a relative path that a walk would not enter, or null. */
+export function skippedSegment(relPath: string): string | null {
+  for (const seg of relPath.split(/[\\/]/)) if (seg && isSkippedName(seg)) return seg;
+  return null;
+}
+
+const DOC_EXT: ReadonlySet<string> = new Set(['.md', '.markdown', '.mdx', '.txt', '.rst', '.adoc', '.asciidoc', '.org']);
+const DOC_NAMES: ReadonlySet<string> = new Set(['readme', 'license', 'licence', 'copying', 'notice', 'changelog', 'authors', 'contributing']);
+/** A license file at the top of a directory: the directory brings its own terms. */
+export const LICENSE_FILE = /^(licen[cs]e|copying)(\.(md|txt|rst))?$/i;
+
+/** Text a person wrote — notes, plans, READMEs, licenses — as opposed to code, data or binaries. */
+export function isDocumentPath(path: string): boolean {
+  const base = path.split(/[\\/]/).pop() ?? '';
+  if (DOC_EXT.has(extname(base).toLowerCase())) return true;
+  return DOC_NAMES.has(base.toLowerCase().replace(/\.[^.]*$/, '')) && !/\.(js|ts|json|py|sh|html|css)$/i.test(base);
+}
+
+/**
+ * What is read from a scope item (Spec §1.1):
+ * - `read`: everything a walk does not skip;
+ * - `documents`: third-party material — only its documents, as `Reference only`;
+ * - `changes`: a worktree registered under a repository in scope — only what it adds to the trunk (E60);
+ * - `history`: a location the project keeps for recovery only — read so it can be cited, never current material
+ *   (its `Used as` follows the project's rule). The rule changes how what is read counts, not what is read (D1): what
+ *   the ignore rules leave out, or a judgement about the location (the Keeper's, the owner's, the program's reading of
+ *   it as build output or someone else's code) left out, stays unread; the program's own guess from a folder's name
+ *   that it holds deleted material (trash/ and the like) gives way to the project's rule, which says what it holds;
+ * - `none`: generated output, what the ignore rules leave out, what the owner excluded.
+ */
+export type Treatment = 'read' | 'documents' | 'changes' | 'history' | 'none';
+
+const recoveryOnly = (item: ScopeItem) => (item.coveredBy ?? []).some((c) => c.category === 'Recovery only');
+/** Left out by the project's ignore rules or by a judgement about the location, not by a Recovery only rule or a folder's name. */
+const leftOutByDecision = (item: ScopeItem) => item.ignoredBy != null || item.classification != null;
+const registeredWorktree = (item: ScopeItem) => item.category === 'Worktree' && (item.relation === 'Worktree of main repo' || item.worktree != null);
+
+export function treatmentOf(item: ScopeItem): Treatment {
+  if (item.category === 'Session source' || item.missing) return 'none';
+  if (item.relation === 'Excluded') return item.addedBy === 'keeper' && recoveryOnly(item) && !leftOutByDecision(item) ? 'history' : 'none';
+  if (item.relation === 'Generated') return 'none';
+  if (item.relation === 'Third-party material') return NOT_READ_KINDS.has(item.classification?.kind ?? '') ? 'none' : 'documents';
+  if (registeredWorktree(item)) return 'changes';
+  return 'read';
+}
+
+/** Items that stand for a location on disk (not session sources), deepest first. */
+const locational = (scope: readonly ScopeItem[]) => scope.filter((i) => i.category !== 'Session source').sort((a, b) => b.path.length - a.path.length);
+
+/** The deepest scope item whose location holds `path`. */
+export function innermostItem(scope: readonly ScopeItem[], path: string): ScopeItem | undefined {
+  return locational(scope).find((i) => isWithin(i.path, path));
+}
+
+/**
+ * Whether a scope item is read at all, given the items above it: under a location that is left out, nothing is read,
+ * except what the owner added by hand and the worktrees registered under the repository (each measured on its own).
+ */
+export function isReadRoot(scope: readonly ScopeItem[], item: ScopeItem): boolean {
+  if (treatmentOf(item) === 'none') return false;
+  if (item.addedBy === 'owner' || registeredWorktree(item)) return true;
+  return !locational(scope).some((o) => o !== item && o.path.length < item.path.length && isWithin(o.path, item.path) && treatmentOf(o) === 'none');
+}
+
+/** How a file is read given the scope: which item it belongs to and the `Used as` its location sets, if any. */
+export function readingOf(scope: readonly ScopeItem[], path: string): { item: ScopeItem | undefined; treatment: Treatment; usedAs: { value: UsedAs; by: 'keeper' | 'owner'; scopeItemId: string } | null } {
+  const item = innermostItem(scope, path);
+  if (!item) return { item, treatment: 'read', usedAs: null };
+  const treatment = treatmentOf(item);
+  const usedAs = treatment === 'documents' && isDocumentPath(path)
+    ? { value: 'Reference only' as const, by: item.classification?.by === 'owner' ? 'owner' as const : 'keeper' as const, scopeItemId: item.id }
+    : null;
+  return { item, treatment, usedAs };
+}
+
+/** Commits of this item are taken as sources: the project's repositories and the worktrees that add something to the trunk. */
+export function readsCommits(item: ScopeItem): boolean {
+  if (item.category !== 'Repository' && item.category !== 'Worktree') return false;
+  const t = treatmentOf(item);
+  if (t !== 'read' && t !== 'changes') return false;
+  const w = item.worktree;
+  // A merged worktree with nothing uncommitted contributes nothing: not its commits, not its status (E60).
+  return !(t === 'changes' && w && w.merged === true && w.uniqueCommits === 0 && w.taken.length === 0);
+}
+
+/** What is read from where, in one comparable line: a change in it means the scan has to run again. */
+export function scanSignature(scope: readonly ScopeItem[]): string {
+  return scope.filter((i) => i.category !== 'Session source').map((i) => `${i.path.toLowerCase()}=${treatmentOf(i)}`).sort().join('\n');
+}

package/src/scope/toolchain.ts

@@ -0,0 +1,180 @@
+/**
+ * Toolchain discovery (Spec §3.1, §6.7; CKC-03 AC-23). The Keeper may read the toolchain the
+ * project's own configuration points at — an SDK, a compiler — to make sense of the build
+ * environment. Those locations are found by the program from the project's own config, using
+ * generic conventions, and become both an allowed read root (src/keeper/bounds) and a Project
+ * scope entry the owner can see and correct (§6.7).
+ *
+ * Only absolute paths a config file *states*, that exist on disk and lie *outside* the project's
+ * own locations, are returned; each carries the config file and the item it came from as its
+ * reason. Version-manager files that name a tool and version but not a path (a version pin, an
+ * install manifest) are intentionally not resolved to guessed install directories — nothing is
+ * added on speculation.
+ *
+ * A declared location that is too broad — a filesystem root, the home directory or anything
+ * containing it, the ProjectKeeper home or anything containing it or inside it, a directory that
+ * contains the project — is still listed so the owner can see and correct it, but flagged
+ * `used: false` with the reason, and never becomes a read root.
+ */
+import { homedir } from 'node:os';
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { basename, dirname, isAbsolute, join } from 'node:path';
+import { canonicalPath, isWithin, normalizePath, pathKey } from '../util/paths.ts';
+import { projectKeeperHome as defaultProjectKeeperHome } from '../store/paths.ts';
+import { broadRootReason } from '../keeper/bounds/paths.ts';
+
+export interface ToolchainRoot {
+  /** Normalised absolute directory the config names. */
+  readonly path: string;
+  /** Which config file, and which item in it, points here (§6.7: reason shown to the owner). */
+  readonly reason: string;
+  /** The config file the location was declared in. */
+  readonly configPath: string;
+  /** Whether it is an allowed read root; false when it is too broad (see notUsedReason). */
+  readonly used: boolean;
+  /** Why it is not used, e.g. "not used: too broad (the whole home directory)"; null when used. */
+  readonly notUsedReason: string | null;
+}
+
+/** The directories a toolchain location is compared against (passed in, so tests never use the real ones). */
+export interface ToolchainOptions {
+  /** The user's home directory. Default: the real one. */
+  readonly home?: string;
+  /** The ProjectKeeper home in use. Default: the configured one. */
+  readonly projectKeeperHome?: string;
+}
+
+/** A property/Gradle-style value: unescape the Java `\:` and `\\` escapes and trim. */
+function unescapeProperty(value: string): string {
+  return value.replace(/\\(.)/g, '$1').trim();
+}
+
+/** A concrete absolute filesystem path, or null for macros ($VAR$, $PROJECT_DIR$), URLs and relatives. */
+function concreteAbsolute(raw: string): string | null {
+  let s = raw.trim().replace(/^["']|["']$/g, '');
+  if (!s || s.includes('$')) return null;                     // IDE/Gradle macros are not concrete
+  if (s.startsWith('file://')) s = s.replace(/^file:\/\//, '');
+  else if (s.startsWith('jar://')) s = s.replace(/^jar:\/\//, '').replace(/!.*$/, '');
+  // A leading slash before a Windows drive from a file:// URL: /C:/x → C:/x
+  if (/^\/[A-Za-z]:[\\/]/.test(s)) s = s.slice(1);
+  if (!isAbsolute(s) && !/^[A-Za-z]:[\\/]/.test(s)) return null;
+  return normalizePath(s);
+}
+
+/** The directory a candidate names: the directory itself, or the parent of a file (a compiler binary). */
+function candidateDir(path: string): string | null {
+  try {
+    const st = statSync(path);
+    return st.isDirectory() ? path : normalizePath(dirname(path));
+  } catch {
+    return null;
+  }
+}
+
+interface RawHit { readonly value: string; readonly where: string }
+
+/** `key = value` lines whose key names a tool location (…dir/home/path/sdk/root). */
+function fromProperties(text: string): RawHit[] {
+  const out: RawHit[] = [];
+  for (const line of text.split(/\r?\n/)) {
+    const m = /^\s*([\w.\-]*(?:dir|home|path|sdk|root))\s*[:=]\s*(.+?)\s*$/i.exec(line);
+    if (m && !line.trimStart().startsWith('#') && !line.trimStart().startsWith('!')) out.push({ value: unescapeProperty(m[2]!), where: m[1]! });
+  }
+  return out;
+}
+
+/** JetBrains library / module roots: url="file://…" or url="jar://…!/…". */
+function fromIdeaXml(text: string): RawHit[] {
+  const out: RawHit[] = [];
+  for (const m of text.matchAll(/url\s*=\s*"((?:file|jar):\/\/[^"]+)"/g)) out.push({ value: m[1]!, where: 'library root' });
+  return out;
+}
+
+/** CMake cache PATH/FILEPATH entries. */
+function fromCMakeCache(text: string): RawHit[] {
+  const out: RawHit[] = [];
+  for (const line of text.split(/\r?\n/)) {
+    const m = /^([^#/][^:=]*):(PATH|FILEPATH)=(.+)$/.exec(line);
+    if (m) out.push({ value: m[3]!, where: `${m[1]!} (${m[2]!})` });
+  }
+  return out;
+}
+
+/** Read a config file if it is present and not too large. */
+function readIfPresent(file: string, maxBytes = 2_000_000): string | null {
+  try {
+    if (!existsSync(file) || statSync(file).size > maxBytes) return null;
+    return readFileSync(file, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+function ideaLibraryFiles(location: string): string[] {
+  const dir = join(location, '.idea', 'libraries');
+  try {
+    return readdirSync(dir).filter((n) => n.toLowerCase().endsWith('.xml')).map((n) => join(dir, n));
+  } catch {
+    return [];
+  }
+}
+
+function topLevelFilesBySuffix(location: string, suffix: string): string[] {
+  try {
+    return readdirSync(location).filter((n) => n.toLowerCase().endsWith(suffix)).map((n) => join(location, n));
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Toolchain roots declared by the project's own configuration. `locations` are the project's own
+ * directories (a path inside one of them is already in scope, so it is never reported as toolchain).
+ */
+export function discoverToolchain(locations: readonly string[], options: ToolchainOptions = {}): ToolchainRoot[] {
+  const roots = locations.map((l) => canonicalPath(l));
+  const breadth = { home: options.home ?? homedir(), projectKeeperHome: options.projectKeeperHome ?? defaultProjectKeeperHome(), projectLocations: roots };
+  const out: ToolchainRoot[] = [];
+  const seen = new Set<string>();
+  const add = (rawValue: string, configPath: string, where: string) => {
+    const abs = concreteAbsolute(rawValue);
+    if (!abs) return;
+    // A configuration file spells a directory its own way; it is kept in the file system's spelling, like the locations.
+    const dir = candidateDir(canonicalPath(abs));
+    if (!dir) return;                                          // must exist on disk
+    if (roots.some((r) => isWithin(r, dir))) return;           // already inside the project
+    const key = pathKey(dir);
+    if (seen.has(key)) return;
+    seen.add(key);
+    const notUsedReason = broadRootReason(dir, breadth);
+    out.push({ path: dir, reason: `${basename(configPath)} declares ${where} → ${dir}`, configPath, used: notUsedReason === null, notUsedReason });
+  };
+
+  for (const location of roots) {
+    if (!existsSync(location)) continue;
+    const props = readIfPresent(join(location, 'local.properties'));
+    if (props) for (const h of fromProperties(props)) add(h.value, join(location, 'local.properties'), h.where);
+    const cmake = readIfPresent(join(location, 'CMakeCache.txt'));
+    if (cmake) for (const h of fromCMakeCache(cmake)) add(h.value, join(location, 'CMakeCache.txt'), h.where);
+    for (const xml of [...ideaLibraryFiles(location), ...topLevelFilesBySuffix(location, '.iml')]) {
+      const text = readIfPresent(xml);
+      if (text) for (const h of fromIdeaXml(text)) add(h.value, xml, h.where);
+    }
+  }
+  return out;
+}
+
+/** A toolchain entry as stored on the project (records written before the used flag existed lack it). */
+export interface StoredToolchainEntry {
+  readonly path: string;
+  readonly used?: boolean;
+  readonly notUsedReason?: string | null;
+}
+
+/**
+ * The toolchain entries the read boundary considers: the ones stored on the project, or discovered now when scope
+ * discovery has not stored any. The boundary re-checks each for breadth itself; the stored flag is for display.
+ */
+export function toolchainRoots(project: { readonly toolchain?: readonly StoredToolchainEntry[]; readonly locations: readonly string[] }, options: ToolchainOptions = {}): readonly StoredToolchainEntry[] {
+  return project.toolchain ? [...project.toolchain] : discoverToolchain(project.locations, options);
+}