@ontrails/source 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,179 @@
+# @ontrails/source
+
+## 0.2.0
+
+### Patch Changes
+
+- [`b3ddf91`](https://github.com/outfitter-dev/trails/commit/b3ddf918ada8211f44983512e2bbdfbc5b66d722): Prepare the first normal Trails release at `0.2.0` on `latest`, replacing the unpublished 1.0.0 source release. The target advances the original `0.1.0` source minor, which was never published under the current package names. Public packages remain in lockstep. Update consumer installation guidance and provide a temporary manifest bridge for old 1.0 beta sources. Published beta versions remain unchanged; minor 0.x releases may carry documented breaking changes.
+
+  The `1.0.0` section retained below records an unpublished preparation, not an npm release. Its accumulated changes are included in `0.2.0`; the section remains as source history alongside the published beta entries.
+
+## 1.0.0
+
+### Minor Changes
+
+- [`90d394c`](https://github.com/outfitter-dev/trails/commit/90d394c005fdf6b898ba7052d0b56755af0f4954): Derive nested worktree, repository, and submodule collection boundaries in the
+  shared Source walker. Regrade and Warden now observe one directly targeted
+  working tree per run, and Regrade audit summaries expose boundary skip counts.
+- [`54d259b`](https://github.com/outfitter-dev/trails/commit/54d259be81fb6c41d85be48a6cb2100c746a7126): Expose parser-native comment spans from `parseWithDiagnostics` so source-aware
+  tooling can distinguish exact JavaScript and TypeScript comment trivia without
+  reimplementing a lexer.
+
+  Use the shared spans in Warden's public-example rule while keeping leading
+  comment ownership fail-closed across JavaScript line terminators.
+
+- [`88a6a62`](https://github.com/outfitter-dev/trails/commit/88a6a62a9e9e230ca6d368fa78dc3ece6c816204): Complete the v1 classification-first cutover from projection/project vocabulary
+  to derive/derived for contract-owned fact production and render/rendered for
+  surface presentation. Public type, helper, rule, relation, and report names move
+  without compatibility aliases; ordinary repository/project nouns remain
+  explicit preserves or structured review inventory.
+- [`35cbe28`](https://github.com/outfitter-dev/trails/commit/35cbe289db46539b3689dbf6cf8ab0e5d9a1b09c): Found `@ontrails/source` as the shared source-code AST kernel for parsing,
+  walking, locations, edits, literals, and generic Trails syntax recognition.
+  Warden, Regrade, Wayfinder, and the Trails operator now import those shared
+  mechanics from `@ontrails/source`; the legacy Warden AST route is removed by the
+  stacked hard cutover.
+
+### Patch Changes
+
+- [`1679687`](https://github.com/outfitter-dev/trails/commit/1679687219431c38cdc7f46de8de60ccac49fd3c): Add Config-owned static `workspace.apps` identity with bounded, non-executing TypeScript extraction, shared data-format validation, convention-derived app entries, and normalized project paths. Type-only wrappers remain transparent, unrelated deployment expressions stay outside identity proof, duplicate identity keys fail before parser collapse, separator aliases cannot create competing app-root owners, and Source preserves declared submodule boundaries when their checkouts are absent. YAML workspace identity must stay literal, JSON-compatible data: alias references and merge keys inside the workspace subtree now fail closed before identity resolution instead of collapsing silently at parse time, while an anchor definition that nothing references stays inert and cannot alter the resolved identity. Invalid discovery start directories also fail closed: a start path that is missing or is not a directory now raises a typed `ValidationError` naming it instead of silently walking up to an ancestor project's identity.
+- [`f556559`](https://github.com/outfitter-dev/trails/commit/f556559b9e8645cf0d2b1763e199ce6efec8ea29): Carries the curated typed AST node guards into `@ontrails/source` so source
+  consumers can narrow common OXC node shapes without assertion casts.
+- [`b1fbe57`](https://github.com/outfitter-dev/trails/commit/b1fbe574e6f44d1fecb5e3a000270955c0a77b7b): Publish Bun-validated package tarballs through an npm trusted-publishing adapter
+  binding, add exact repository metadata for each public workspace package, and
+  correct the native Bun release descriptor to its pack-only runtime boundary.
+- [`3531b58`](https://github.com/outfitter-dev/trails/commit/3531b58ba5320753d6d2594257ef71bc950d28a1): Add the advisory captured-kernel Warden rule for ownership review when a public
+  subpath re-exports package internals and multiple production workspaces consume
+  that subpath, including import-then-export barrels that preserve the internal
+  binding through a local alias or default export.
+
+  Expose typed import-kind inspection from `@ontrails/source` so project rules
+  can keep erased type bindings separate from runtime exports.
+
+- [`10f2492`](https://github.com/outfitter-dev/trails/commit/10f24928d3bc9d995abf7aa261ecf515c295855d): Own the `wayfind.outline` implementation in the Trails operator app while preserving the existing `trails wayfind file <file> --outline` CLI and MCP composition behavior, and document `@ontrails/source` as the operator's live-source analysis kernel.
+- [`35e5fed`](https://github.com/outfitter-dev/trails/commit/35e5fedd228e498783f479f0dd502e2f3ec772b8): Fold the Wayfinder graph-read catalog into `@ontrails/topography`. Wayfind
+  remains the product, trail-id, CLI, and MCP brand, but there is no longer an
+  `@ontrails/wayfinder` package to install or import. Programmatic consumers
+  should move imports such as `wayfinderTopo`, `wayfindOverviewTrail`,
+  `loadWayfinderArtifacts`, and the Wayfinder filter/provenance types to
+  `@ontrails/topography`.
+
+  Expose that package move as a governed Regrade transition so exact
+  `@ontrails/wayfinder` imports can move safely while product vocabulary and near
+  routes remain unchanged for review. Regrade routes package manifests through
+  structured review instead of rewriting dependency keys as plain text.
+
+  The Trails operator now reads all `wayfind.*` query trails and artifact helpers
+  from `@ontrails/topography` while preserving the existing CLI/MCP schemas,
+  route IDs, output shapes, and internal trail visibility.
+
+- [`3a65ae3`](https://github.com/outfitter-dev/trails/commit/3a65ae363e05b7589f4a9876da4346886353b48c): Rename the durable graph substrate package from `@ontrails/topographer` to
+  `@ontrails/topography` after folding Wayfind graph queries into that owner.
+
+  Update imports to `@ontrails/topography` or
+  `@ontrails/topography/backend-support`. The pre-1.0 cutover does not ship a
+  compatibility package. TopoGraph, lock, topo-store, semantic diff, and Wayfind
+  APIs keep their existing contracts, and the `trails wayfind` CLI and MCP names
+  remain unchanged.
+
+  The governed package-route transition moves legacy `@ontrails/wayfinder`
+  imports directly to `@ontrails/topography`; it does not emit the retired
+  intermediate `@ontrails/topographer` route.
+
+## 1.0.0-beta.50
+
+## 1.0.0-beta.49
+
+## 1.0.0-beta.48
+
+## 1.0.0-beta.47
+
+### Minor Changes
+
+- [`90d394c`](https://github.com/outfitter-dev/trails/commit/90d394c005fdf6b898ba7052d0b56755af0f4954): Derive nested worktree, repository, and submodule collection boundaries in the
+  shared Source walker. Regrade and Warden now observe one directly targeted
+  working tree per run, and Regrade audit summaries expose boundary skip counts.
+
+## 1.0.0-beta.46
+
+### Minor Changes
+
+- [`54d259b`](https://github.com/outfitter-dev/trails/commit/54d259be81fb6c41d85be48a6cb2100c746a7126): Expose parser-native comment spans from `parseWithDiagnostics` so source-aware
+  tooling can distinguish exact JavaScript and TypeScript comment trivia without
+  reimplementing a lexer.
+
+  Use the shared spans in Warden's public-example rule while keeping leading
+  comment ownership fail-closed across JavaScript line terminators.
+
+## 1.0.0-beta.45
+
+## 1.0.0-beta.44
+
+### Patch Changes
+
+- [`b1fbe57`](https://github.com/outfitter-dev/trails/commit/b1fbe574e6f44d1fecb5e3a000270955c0a77b7b): Publish Bun-validated package tarballs through an npm trusted-publishing adapter
+  binding, add exact repository metadata for each public workspace package, and
+  correct the native Bun release descriptor to its pack-only runtime boundary.
+
+## 1.0.0-beta.43
+
+### Minor Changes
+
+- [`88a6a62`](https://github.com/outfitter-dev/trails/commit/88a6a62a9e9e230ca6d368fa78dc3ece6c816204): Complete the v1 classification-first cutover from projection/project vocabulary
+  to derive/derived for contract-owned fact production and render/rendered for
+  surface presentation. Public type, helper, rule, relation, and report names move
+  without compatibility aliases; ordinary repository/project nouns remain
+  explicit preserves or structured review inventory.
+
+## 1.0.0-beta.42
+
+## 1.0.0-beta.41
+
+## 1.0.0-beta.40
+
+### Minor Changes
+
+- [`35cbe28`](https://github.com/outfitter-dev/trails/commit/35cbe289db46539b3689dbf6cf8ab0e5d9a1b09c): Found `@ontrails/source` as the shared source-code AST kernel for parsing,
+  walking, locations, edits, literals, and generic Trails syntax recognition.
+  Warden, Regrade, Wayfinder, and the Trails operator now import those shared
+  mechanics from `@ontrails/source`; the legacy Warden AST route is removed by the
+  stacked hard cutover.
+
+### Patch Changes
+
+- [`3531b58`](https://github.com/outfitter-dev/trails/commit/3531b58ba5320753d6d2594257ef71bc950d28a1): Add the advisory captured-kernel Warden rule for ownership review when a public
+  subpath re-exports package internals and multiple production workspaces consume
+  that subpath, including import-then-export barrels that preserve the internal
+  binding through a local alias or default export.
+
+  Expose typed import-kind inspection from `@ontrails/source` so project rules
+  can keep erased type bindings separate from runtime exports.
+
+- [`10f2492`](https://github.com/outfitter-dev/trails/commit/10f24928d3bc9d995abf7aa261ecf515c295855d): Own the `wayfind.outline` implementation in the Trails operator app while preserving the existing `trails wayfind file <file> --outline` CLI and MCP composition behavior, and document `@ontrails/source` as the operator's live-source analysis kernel.
+- [`35e5fed`](https://github.com/outfitter-dev/trails/commit/35e5fedd228e498783f479f0dd502e2f3ec772b8): Fold the Wayfinder graph-read catalog into `@ontrails/topography`. Wayfind
+  remains the product, trail-id, CLI, and MCP brand, but there is no longer an
+  `@ontrails/wayfinder` package to install or import. Programmatic consumers
+  should move imports such as `wayfinderTopo`, `wayfindOverviewTrail`,
+  `loadWayfinderArtifacts`, and the Wayfinder filter/provenance types to
+  `@ontrails/topography`.
+
+  Expose that package move as a governed Regrade transition so exact
+  `@ontrails/wayfinder` imports can move safely while product vocabulary and near
+  routes remain unchanged for review. Regrade routes package manifests through
+  structured review instead of rewriting dependency keys as plain text.
+
+  The Trails operator now reads all `wayfind.*` query trails and artifact helpers
+  from `@ontrails/topography` while preserving the existing CLI/MCP schemas,
+  route IDs, output shapes, and internal trail visibility.
+
+- [`3a65ae3`](https://github.com/outfitter-dev/trails/commit/3a65ae363e05b7589f4a9876da4346886353b48c): Rename the durable graph substrate package from `@ontrails/topographer` to
+  `@ontrails/topography` after folding Wayfind graph queries into that owner.
+
+  Update imports to `@ontrails/topography` or
+  `@ontrails/topography/backend-support`. The pre-1.0 cutover does not ship a
+  compatibility package. TopoGraph, lock, topo-store, semantic diff, and Wayfind
+  APIs keep their existing contracts, and the `trails wayfind` CLI and MCP names
+  remain unchanged.
+
+  The governed package-route transition moves legacy `@ontrails/wayfinder`
+  imports directly to `@ontrails/topography`; it does not emit the retired
+  intermediate `@ontrails/topographer` route.

package/README.md

@@ -0,0 +1,96 @@
+# @ontrails/source
+
+Shared source-code machinery for Trails packages and repo tooling.
+
+`source` means source code: TypeScript and JavaScript text parsed into an OXC AST. It does not mean activation source, signal source, data source, event source, or execution source.
+
+## What It Owns
+
+`@ontrails/source` owns reusable source-code mechanics:
+
+- AST node guards and accessors for the OXC node shapes Trails tooling uses.
+- `parse` and `parseWithDiagnostics` wrappers over `oxc-parser`, including
+  parser-native comment spans for tools that must distinguish source trivia.
+- `walk`, parent-aware walking, and scope-aware walking over `oxc-walker`.
+- Source locations, source edits, literal extraction, and generic Trails syntax recognition.
+- Generic trail/entity discovery helpers such as `findTrailDefinitions`, `findImplementationBodies`, `findEntityDefinitions`, and `isImplementationCall`.
+
+The package root is the public API. Import from `@ontrails/source`; there are no supported `/ast`, `/trails`, or `/utils` subpaths.
+
+## Package Admission Test
+
+`@ontrails/source` exists because the same source-code contract is reused by independent toolchain owners:
+
+- Warden uses it to implement source-static governance without owning the parser facade.
+- Regrade uses it for safe downstream source rewrites.
+- The Trails operator uses it to assemble live source-file outlines.
+- The `trails` operator uses it for draft promotion and version-lifecycle support.
+
+The package is admitted only for reusable source machinery with at least two independent toolchain owners and a genuinely shared contract. It must not absorb product verdicts, release plans, query semantics, rendering, Warden rule policy, Regrade engines, Topography artifact assembly, or Wayfinder answer composition.
+
+This boundary follows the package-worthiness rule in [ADR-0051: Package Ownership Follows Natural Altitude](../../docs/adr/0051-package-ownership-follows-natural-altitude.md): move code when the natural owner is above one consumer, not when a file merely feels crowded.
+
+## Examples
+
+Parse source and inspect trail declarations:
+
+```ts
+import { findTrailDefinitions, parse } from '@ontrails/source';
+
+const ast = parse(
+  'example.ts',
+  "import { trail } from '@ontrails/core';\nexport const show = trail('user.show', {});\n"
+);
+
+const trailIds = ast ? findTrailDefinitions(ast).map((trail) => trail.id) : [];
+```
+
+Inspect exact comment spans without rebuilding a JavaScript or TypeScript lexer:
+
+```ts
+import { parseWithDiagnostics } from '@ontrails/source';
+
+const sourceCode = '/** Describe a trail. */\nexport const show = 1;\n';
+const parsed = parseWithDiagnostics('example.ts', sourceCode);
+const comments = parsed.comments.map((comment) => ({
+  ...comment,
+  source: sourceCode.slice(comment.start, comment.end),
+}));
+```
+
+Comment spans are returned only when the parser reports no diagnostics. Tools must treat an empty comment inventory on a recovered parse as unknown rather than as proof that the source contains no comments.
+
+Walk source with parent context:
+
+```ts
+import { parse, walkWithParents } from '@ontrails/source';
+
+const ast = parse('example.ts', 'const value = trail("demo.show", {});\n');
+const callParents: string[] = [];
+
+if (ast) {
+  walkWithParents(ast, (node, context) => {
+    if (node.type === 'CallExpression') {
+      callParents.push(`${context.parent?.type ?? 'root'}:${String(context.key)}`);
+    }
+  });
+}
+```
+
+Apply source edits:
+
+```ts
+import { applySourceEdits, createSourceEdit } from '@ontrails/source';
+
+const updated = applySourceEdits('const name = "old";\n', [
+  createSourceEdit(14, 17, 'new'),
+]);
+```
+
+## Non-Goals
+
+- Warden rule policy and rule-specific facts remain in `@ontrails/warden`.
+- Regrade migration planning and execution remain in `@ontrails/regrade`.
+- Topography graph artifacts and outline assembly remain outside this package.
+- Wayfind query trails and answer rendering remain in `@ontrails/topography`.
+- Runtime Trails contracts remain in `@ontrails/core`.

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@ontrails/source",
+  "version": "0.2.0",
+  "description": "Shared source-code AST parsing, walking, location, edit, literal, and Trails syntax helpers.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/outfitter-dev/trails.git",
+    "directory": "packages/source"
+  },
+  "files": [
+    "src/**/*.ts",
+    "!src/**/__tests__/**",
+    "!src/**/*.test.ts",
+    "!src/**/*.test-d.ts",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "lint": "oxlint ./src",
+    "clean": "rm -rf dist *.tsbuildinfo"
+  },
+  "dependencies": {
+    "oxc-parser": "^0.121.0",
+    "oxc-walker": "^1.0.0"
+  }
+}

package/src/collection.ts

@@ -0,0 +1,329 @@
+import { spawnSync } from 'node:child_process';
+import { lstatSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import type { Dirent } from 'node:fs';
+import { join, posix, relative, resolve, sep } from 'node:path';
+
+/** Git-derived reasons a nested directory is outside the current observation tree. */
+export type SourceCollectionBoundaryReason =
+  | 'nested-repository'
+  | 'nested-worktree'
+  | 'submodule-boundary';
+
+/** Filesystem entry kinds exposed to a source-collection policy. */
+export type SourceCollectionEntryKind = 'directory' | 'file' | 'other';
+
+/** A root-relative filesystem entry offered to a source-collection policy. */
+export interface SourceCollectionEntry {
+  readonly kind: SourceCollectionEntryKind;
+  readonly name: string;
+  readonly path: string;
+}
+
+/** The action a source-collection policy chooses for one entry. */
+export type SourceCollectionDecision =
+  | { readonly action: 'collect' }
+  | { readonly action: 'recurse' }
+  | { readonly action: 'skip'; readonly reason: string };
+
+/** One collected file, with both absolute and root-relative identities. */
+export interface CollectedSourceFile {
+  readonly absolutePath: string;
+  readonly path: string;
+}
+
+/** One visible collection skip. */
+export interface SkippedSourceEntry {
+  readonly path: string;
+  readonly reason: string;
+}
+
+/** Deterministic result of observing one source tree. */
+export interface SourceTreeCollection {
+  readonly files: readonly CollectedSourceFile[];
+  readonly root: string;
+  readonly skipped: readonly SkippedSourceEntry[];
+}
+
+/** Consumer policy for ordinary entries after Git boundaries are derived. */
+export interface CollectSourceTreeOptions {
+  readonly classify?: (
+    entry: SourceCollectionEntry
+  ) => SourceCollectionDecision;
+}
+
+const toPosixRelative = (root: string, absolutePath: string): string => {
+  const path = relative(root, absolutePath);
+  return sep === posix.sep ? path : path.split(sep).join(posix.sep);
+};
+
+const entryKind = (entry: {
+  isDirectory(): boolean;
+  isFile(): boolean;
+}): SourceCollectionEntryKind => {
+  if (entry.isDirectory()) {
+    return 'directory';
+  }
+  return entry.isFile() ? 'file' : 'other';
+};
+
+const defaultDecision = (
+  entry: SourceCollectionEntry
+): SourceCollectionDecision => {
+  if (entry.kind === 'directory') {
+    return { action: 'recurse' };
+  }
+  return entry.kind === 'file'
+    ? { action: 'collect' }
+    : { action: 'skip', reason: 'unsupported-entry' };
+};
+
+interface SubmodulePathSnapshot {
+  readonly paths: ReadonlySet<string>;
+  readonly readable: boolean;
+}
+
+const readSubmodulePaths = (root: string): SubmodulePathSnapshot => {
+  const gitmodulesPath = join(root, '.gitmodules');
+  let metadataStats: ReturnType<typeof lstatSync>;
+  try {
+    metadataStats = lstatSync(gitmodulesPath);
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code === 'ENOENT'
+      ? { paths: new Set(), readable: true }
+      : { paths: new Set(), readable: false };
+  }
+  if (!metadataStats.isFile()) {
+    return { paths: new Set(), readable: false };
+  }
+
+  let source: string;
+  try {
+    source = readFileSync(gitmodulesPath, 'utf8');
+  } catch {
+    return { paths: new Set(), readable: false };
+  }
+  const parsed = spawnSync(
+    'git',
+    ['config', '--file', '-', '--null', '--get-regexp', '^submodule\\.'],
+    { encoding: 'utf8', input: source }
+  );
+  if (parsed.status === 1) {
+    const hasOnlyComments = source
+      .split(/\r?\n/)
+      .every((line) => !line.trim() || /^[#;]/.test(line.trim()));
+    return {
+      paths: new Set(),
+      readable: hasOnlyComments,
+    };
+  }
+  if (parsed.status !== 0) {
+    return { paths: new Set(), readable: false };
+  }
+
+  const paths = new Set<string>();
+  const owners = new Set<string>();
+  const ownersWithPaths = new Set<string>();
+  const authoredSubmodules = new Set(
+    [
+      ...source.matchAll(
+        /^\s*\[\s*submodule(?:\s+"((?:[^"\\]|\\.)*)"|\.([^\]]+?))\s*\]/gim
+      ),
+    ].map((match) => match[1] ?? match[2]?.trim())
+  );
+  for (const record of parsed.stdout.split('\0').filter(Boolean)) {
+    const separator = record.indexOf('\n');
+    if (separator === -1) {
+      return { paths: new Set(), readable: false };
+    }
+    const key = record.slice(0, separator);
+    const fieldSeparator = key.lastIndexOf('.');
+    if (fieldSeparator <= 'submodule.'.length) {
+      return { paths: new Set(), readable: false };
+    }
+    const owner = key.slice('submodule.'.length, fieldSeparator);
+    owners.add(owner);
+    if (key.slice(fieldSeparator + 1).toLowerCase() !== 'path') {
+      continue;
+    }
+    const value = record.slice(separator + 1);
+    if (!value) {
+      return { paths: new Set(), readable: false };
+    }
+    const authoredPath = value.replaceAll('\\', '/');
+    const path = posix.normalize(authoredPath).replace(/\/+$/, '');
+    if (
+      posix.isAbsolute(authoredPath) ||
+      path === '.' ||
+      path === '..' ||
+      path.startsWith('../') ||
+      /^[A-Za-z][A-Za-z\d+.-]*:/u.test(path)
+    ) {
+      return { paths: new Set(), readable: false };
+    }
+    ownersWithPaths.add(owner);
+    paths.add(path);
+  }
+  return owners.size === ownersWithPaths.size &&
+    authoredSubmodules.size === ownersWithPaths.size
+    ? { paths, readable: true }
+    : { paths: new Set(), readable: false };
+};
+
+const boundaryReason = (
+  absoluteDirectory: string,
+  path: string,
+  submodules: SubmodulePathSnapshot
+): SourceCollectionBoundaryReason | 'unreadable-git-boundary' | undefined => {
+  if (!submodules.readable) {
+    return 'unreadable-git-boundary';
+  }
+  if (submodules.paths.has(path)) {
+    return 'submodule-boundary';
+  }
+
+  const marker = join(absoluteDirectory, '.git');
+  let markerStats: ReturnType<typeof lstatSync>;
+  try {
+    markerStats = lstatSync(marker);
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code === 'ENOENT'
+      ? undefined
+      : 'unreadable-git-boundary';
+  }
+
+  try {
+    if (markerStats.isDirectory()) {
+      return statSync(join(marker, 'HEAD')).isFile() &&
+        statSync(join(marker, 'objects')).isDirectory()
+        ? 'nested-repository'
+        : 'unreadable-git-boundary';
+    }
+    if (!markerStats.isFile()) {
+      return 'unreadable-git-boundary';
+    }
+
+    const pointer = readFileSync(marker, 'utf8').match(/^gitdir:\s*(.+?)\s*$/);
+    const gitDirectory = pointer?.[1];
+    if (!gitDirectory) {
+      return 'unreadable-git-boundary';
+    }
+    const resolvedGitDirectory = resolve(absoluteDirectory, gitDirectory);
+    return statSync(resolvedGitDirectory).isDirectory() &&
+      statSync(join(resolvedGitDirectory, 'HEAD')).isFile()
+      ? 'nested-worktree'
+      : 'unreadable-git-boundary';
+  } catch {
+    return 'unreadable-git-boundary';
+  }
+};
+
+const comparePath = (
+  left: { readonly path: string },
+  right: {
+    readonly path: string;
+  }
+): number => {
+  if (left.path < right.path) {
+    return -1;
+  }
+  return left.path > right.path ? 1 : 0;
+};
+
+/**
+ * Collect files from exactly one working tree, pruning nested Git observations.
+ *
+ * Git boundaries take precedence over consumer policy so a tool cannot scan a
+ * nested checkout and hide that fact behind an authored exclude. The supplied
+ * root remains first-class: only directories encountered beneath it are
+ * classified as boundaries.
+ *
+ * @example
+ * ```ts
+ * const result = collectSourceTree(process.cwd(), {
+ *   classify: (entry) =>
+ *     entry.kind === 'file' && entry.path.endsWith('.ts')
+ *       ? { action: 'collect' }
+ *       : entry.kind === 'directory'
+ *         ? { action: 'recurse' }
+ *         : { action: 'skip', reason: 'unsupported-extension' },
+ * });
+ * ```
+ */
+export const collectSourceTree = (
+  root: string,
+  options: CollectSourceTreeOptions = {}
+): SourceTreeCollection | null => {
+  const absoluteRoot = resolve(root);
+  let rootEntries: readonly Dirent<string>[];
+  try {
+    rootEntries = readdirSync(absoluteRoot, { withFileTypes: true });
+  } catch {
+    return null;
+  }
+
+  const classify = options.classify ?? defaultDecision;
+  const submodules = readSubmodulePaths(absoluteRoot);
+  const files: CollectedSourceFile[] = [];
+  const skipped: SkippedSourceEntry[] = submodules.readable
+    ? [...submodules.paths].map((path) => ({
+        path,
+        reason: 'submodule-boundary',
+      }))
+    : [{ path: '.gitmodules', reason: 'unreadable-git-metadata' }];
+  const queue: {
+    readonly absolutePath: string;
+    readonly entries?: readonly Dirent<string>[];
+  }[] = [{ absolutePath: absoluteRoot, entries: rootEntries }];
+
+  while (queue.length > 0) {
+    const current = queue.shift() as (typeof queue)[number];
+    let { entries } = current;
+    if (!entries) {
+      try {
+        entries = readdirSync(current.absolutePath, { withFileTypes: true });
+      } catch {
+        skipped.push({
+          path: toPosixRelative(absoluteRoot, current.absolutePath),
+          reason: 'unreadable-directory',
+        });
+        continue;
+      }
+    }
+
+    for (const entry of entries) {
+      const absolutePath = join(current.absolutePath, entry.name);
+      const path = toPosixRelative(absoluteRoot, absolutePath);
+      const kind = entryKind(entry);
+      if (path === '.gitmodules' && !submodules.readable) {
+        continue;
+      }
+      if (submodules.paths.has(path)) {
+        continue;
+      }
+      if (kind === 'directory') {
+        const reason = boundaryReason(absolutePath, path, submodules);
+        if (reason) {
+          skipped.push({ path, reason });
+          continue;
+        }
+      }
+      if (entry.name === '.git') {
+        skipped.push({ path, reason: 'ignored-directory' });
+        continue;
+      }
+
+      const decision = classify({ kind, name: entry.name, path });
+      if (decision.action === 'collect') {
+        files.push({ absolutePath, path });
+      } else if (decision.action === 'recurse') {
+        queue.push({ absolutePath });
+      } else {
+        skipped.push({ path, reason: decision.reason });
+      }
+    }
+  }
+
+  files.sort(comparePath);
+  skipped.sort(comparePath);
+  return { files, root: absoluteRoot, skipped };
+};