@latysh-development/monolith 0.1.0-alpha.0 → 0.1.0-alpha.1

package/dist/discovery/orchestrate.js

@@ -0,0 +1,32 @@
+/**
+ * DISCOVERY-001C-G — unified discovery orchestration (ADR-021). Internal.
+ *
+ * One entry point that runs the whole Project Discovery chain: ONE safe traversal, then fact
+ * extraction and documentation analysis over that same `TraversalResult` object and the same
+ * `projectRoot` string, then the composer.
+ *
+ * Guarantees, by construction of this function:
+ *  - same invocation: both results come from one call;
+ *  - same traversal: exactly one `traverseProject` call; both analyzers receive that object;
+ *  - same project root: the one string given here is passed unchanged to all three steps.
+ *
+ * NOT guaranteed: same file system snapshot. The traversal records a listing; the analyzers read
+ * file contents (package.json, Markdown documents) later and independently, so a file may change
+ * between the listing and either read, or between the two reads. `reproducible`/`completeness`
+ * remain the only signals about that.
+ *
+ * Errors from any step propagate unchanged; nothing is retried, caught or replaced by a fallback.
+ * No other data source, no network, no model, no write. The existing path-safety and bounded-read
+ * rules live inside the steps and are not bypassed here.
+ */
+import { analyzeDocumentation } from './docs.js';
+import { composeProjectMap } from './compose.js';
+import { extractProjectFacts } from './facts.js';
+import { traverseProject } from './traverse.js';
+/** Runs traversal → facts + documentation (same traversal object) → composer and returns the Project Map Markdown. */
+export function discoverProjectMap(projectRoot, options = {}) {
+    const traversal = traverseProject(projectRoot, options.traversal);
+    const discovery = extractProjectFacts(projectRoot, traversal, options.facts);
+    const documentation = analyzeDocumentation(projectRoot, traversal, options.documentation);
+    return composeProjectMap(discovery, documentation);
+}

package/dist/discovery/render.d.ts

@@ -0,0 +1,36 @@
+/**
+ * DISCOVERY-001B-3 — deterministic Markdown renderer for a `DiscoveryResult` (ADR-021). Internal.
+ *
+ * A pure transformation: it takes a result that `validateDiscoveryResult` accepts and returns text.
+ * It reads no file, opens no connection, starts no process, calls no model, keeps no clock and writes
+ * nothing. It reports what the result contains and nothing else; in particular it draws no
+ * architectural conclusion. A valid result is not independent evidence of what the project contains,
+ * so every statement is phrased as an observation, a declaration, a candidate or a report.
+ *
+ * Markdown safety. Every string that comes from the scanned project or from the result (paths,
+ * names, languages, rules, messages, codes) goes through `code()` and is only ever placed inside an
+ * inline code span in a list item. Headings, list structure and section titles are fixed text, so
+ * project data cannot create a heading, a list item, a link, HTML, a code fence or a new section.
+ */
+import { type DiscoveryResult } from './contracts.js';
+/**
+ * The one way an untrusted string enters the document: an inline code span. Inside a code span
+ * Markdown and HTML are not interpreted. The fence is one backtick longer than the longest backtick
+ * run in the text, so the text cannot close it; padding keeps leading/trailing backticks and spaces.
+ */
+declare function code(text: string): string;
+/**
+ * Renders a Project Map Proposal for a `DiscoveryResult`.
+ *
+ * Throws `DiscoveryError('RESULT_INVALID')` if the result does not satisfy `validateDiscoveryResult`
+ * (which includes the canonical order of facts, sources and diagnostics). The message carries the
+ * first violations, which by the validator's own design name a location and a rule and never repeat
+ * a value from the input. The input is not modified.
+ *
+ * The size of the output is linear in the size of the (bounded) result: every untrusted string is cut
+ * at `MAX_SHOWN_CODE_POINTS` and no section lists more than the result holds.
+ */
+export declare function renderProjectMapProposal(result: DiscoveryResult): string;
+/** Internal (DISCOVERY-001C): the one safe way to place an untrusted string in Markdown, shared with the composer. */
+export { code as markdownCodeSpan };
+//# sourceMappingURL=render.d.ts.map

package/dist/discovery/render.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../../src/discovery/render.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAWL,KAAK,eAAe,EAGrB,MAAM,gBAAgB,CAAC;AA6BxB;;;;GAIG;AACH,iBAAS,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAUlC;AAsDD;;;;;;;;;;GAUG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM,CA2JxE;AAED,sHAAsH;AACtH,OAAO,EAAE,IAAI,IAAI,gBAAgB,EAAE,CAAC"}

package/dist/discovery/render.js

@@ -0,0 +1,278 @@
+/**
+ * DISCOVERY-001B-3 — deterministic Markdown renderer for a `DiscoveryResult` (ADR-021). Internal.
+ *
+ * A pure transformation: it takes a result that `validateDiscoveryResult` accepts and returns text.
+ * It reads no file, opens no connection, starts no process, calls no model, keeps no clock and writes
+ * nothing. It reports what the result contains and nothing else; in particular it draws no
+ * architectural conclusion. A valid result is not independent evidence of what the project contains,
+ * so every statement is phrased as an observation, a declaration, a candidate or a report.
+ *
+ * Markdown safety. Every string that comes from the scanned project or from the result (paths,
+ * names, languages, rules, messages, codes) goes through `code()` and is only ever placed inside an
+ * inline code span in a list item. Headings, list structure and section titles are fixed text, so
+ * project data cannot create a heading, a list item, a link, HTML, a code fence or a new section.
+ */
+import { DEPENDENCY_SECTIONS, DiscoveryError, EXTRACTION_DIAGNOSTIC_AFFECTS_COMPLETENESS, FACT_LEVEL_BY_KIND, sourceCoverage, validateDiscoveryResult, } from './contracts.js';
+/**
+ * Longest untrusted string shown, in code points. Not a new limit: it is the contract's own maximum
+ * for a project-relative path (`isSafeRelativePath` in contracts.ts, 4096). Dependency and script names are already
+ * bounded by `limits.maxNameLength`; this bound covers the strings the contract leaves free
+ * (diagnostic messages, language names, rule names).
+ */
+const MAX_SHOWN_CODE_POINTS = 4096;
+// Control, format (bidirectional marks and overrides, zero-width, soft hyphen, tags), line and paragraph
+// separators, and surrogates. Shown as `[U+XXXX]` so that they cannot reorder, hide or break text.
+const NOT_SHOWN_AS_IS = /^[\p{Cc}\p{Cf}\p{Zl}\p{Zp}\p{Cs}]$/u;
+function visible(text) {
+    let out = '';
+    let n = 0;
+    for (const ch of text) {
+        if (n === MAX_SHOWN_CODE_POINTS) {
+            out += `…[truncated; ${text.length} UTF-16 units in total]`;
+            break;
+        }
+        n++;
+        if (NOT_SHOWN_AS_IS.test(ch))
+            out += `[U+${ch.codePointAt(0).toString(16).toUpperCase().padStart(4, '0')}]`;
+        else
+            out += ch;
+    }
+    return out;
+}
+/**
+ * The one way an untrusted string enters the document: an inline code span. Inside a code span
+ * Markdown and HTML are not interpreted. The fence is one backtick longer than the longest backtick
+ * run in the text, so the text cannot close it; padding keeps leading/trailing backticks and spaces.
+ */
+function code(text) {
+    const shown = visible(text);
+    if (shown.length === 0)
+        return '(empty)';
+    let longest = 0;
+    for (const run of shown.match(/`+/g) ?? [])
+        longest = Math.max(longest, run.length);
+    const fence = '`'.repeat(longest + 1);
+    // CommonMark strips one space from each side only when the content is not all spaces, so a
+    // spaces-only value gets no padding: it is shown with exactly the spaces it has.
+    const pad = !/^ +$/.test(shown) && /^[` ]|[` ]$/.test(shown) ? ' ' : '';
+    return `${fence}${pad}${shown}${pad}${fence}`;
+}
+const plural = (n, one, many) => `${n} ${n === 1 ? one : many}`;
+function sourceText(s) {
+    return s.field === undefined ? code(s.path) : `${code(s.path)} at ${code(s.field)}`;
+}
+const LIMIT_LABELS = {
+    maxDirectoryFacts: 'directory facts',
+    maxDirectoryDepth: 'directory depth',
+    maxLanguageFacts: 'language facts',
+    maxManifestFacts: 'manifest facts',
+    maxManifestReads: 'manifest reads',
+    maxManifestBytes: 'manifest size, bytes',
+    maxDependenciesPerManifest: 'dependency facts per manifest',
+    maxScriptsPerManifest: 'script facts per manifest',
+    maxEntrypointFacts: 'entrypoint candidate facts',
+    maxFacts: 'facts in total',
+    maxDiagnostics: 'diagnostics',
+    maxNameLength: 'dependency or script name length',
+    maxSourcesPerFact: 'sources listed for a language aggregate',
+};
+const KIND_ORDER = Object.keys(FACT_LEVEL_BY_KIND);
+function ofKind(facts, kind) {
+    return facts.filter((f) => f.kind === kind);
+}
+/** Groups facts by subject, keeping the (already canonical) order of first appearance. */
+function bySubject(facts) {
+    const groups = new Map();
+    for (const f of facts) {
+        const g = groups.get(f.subject);
+        if (g)
+            g.push(f);
+        else
+            groups.set(f.subject, [f]);
+    }
+    return groups;
+}
+function diagnosticLine(d) {
+    const known = Object.prototype.hasOwnProperty.call(EXTRACTION_DIAGNOSTIC_AFFECTS_COMPLETENESS, d.code);
+    const origin = d.code.startsWith('TRAVERSAL_')
+        ? 'reported by the traversal'
+        : known && EXTRACTION_DIAGNOSTIC_AFFECTS_COMPLETENESS[d.code]
+            ? 'extraction; makes the result PARTIAL'
+            : 'extraction; does not by itself make the result PARTIAL';
+    const parts = [`${code(d.code)} (${origin})`];
+    if (d.path !== undefined)
+        parts.push(`path ${code(d.path)}`);
+    if (d.count !== undefined)
+        parts.push(`count ${d.count}`);
+    return `- ${parts.join(', ')}: ${code(d.message)}`;
+}
+/**
+ * Renders a Project Map Proposal for a `DiscoveryResult`.
+ *
+ * Throws `DiscoveryError('RESULT_INVALID')` if the result does not satisfy `validateDiscoveryResult`
+ * (which includes the canonical order of facts, sources and diagnostics). The message carries the
+ * first violations, which by the validator's own design name a location and a rule and never repeat
+ * a value from the input. The input is not modified.
+ *
+ * The size of the output is linear in the size of the (bounded) result: every untrusted string is cut
+ * at `MAX_SHOWN_CODE_POINTS` and no section lists more than the result holds.
+ */
+export function renderProjectMapProposal(result) {
+    const violations = validateDiscoveryResult(result);
+    if (violations.length > 0) {
+        throw new DiscoveryError('RESULT_INVALID', `cannot render: the result failed validation (${violations.length} violation(s)): ${violations.slice(0, 3).join('; ')}`);
+    }
+    const { facts, diagnostics, stats, limits } = result;
+    const partial = result.completeness === 'PARTIAL';
+    const out = [];
+    const line = (s = '') => void out.push(s);
+    line('# Project Map Proposal');
+    line();
+    line('This document reports the contents of a Discovery result. It lists observed, declared and candidate items; it is a proposal for a reader to review, not a verified description of the project. A valid result is not independent evidence of what the project contains.');
+    // ---------------------------------------------------------------- status
+    line();
+    line('## Discovery Status');
+    line();
+    line(`- Completeness: ${result.completeness}`);
+    line(partial
+        ? '  - Some information may have been skipped. Facts that were extracted are shown below; see Limitations for the diagnostics.'
+        : '  - The scan covered the scope it declared. This does not mean that every aspect of the project was examined.');
+    line(`- Reproducible: ${result.reproducible ? 'Yes' : 'No'}`);
+    if (!result.reproducible)
+        line('  - A second scan of the unchanged tree might not return this result.');
+    line(`- Traversal: completeness ${result.traversal.completeness}, reproducible ${result.traversal.reproducible ? 'Yes' : 'No'}`);
+    line(`- Schema version: ${result.schemaVersion}`);
+    line('- Analysed manifest format: package.json only.');
+    line('  - Other recognised manifest names are reported as present; their content was not analysed. Documentation files were not analysed.');
+    line(`- Traversal entries received: ${stats.inputEntries} (${stats.excludedEntries} did not reach extraction)`);
+    line(`- Manifests found: ${stats.manifestsFound}; package.json reads attempted: ${stats.manifestsRead} (an attempt may have failed; see Limitations)`);
+    line(`- Facts recorded: ${stats.facts}`);
+    // ------------------------------------------------------------- structure
+    line();
+    line('## Project Structure');
+    line();
+    const directories = ofKind(facts, 'DIRECTORY');
+    if (directories.length === 0)
+        line('- No directory entries were observed.');
+    else {
+        line(`- Observed directories (${directories.length}, down to depth ${limits.maxDirectoryDepth}):`);
+        for (const f of directories)
+            line(`  - ${code(f.subject)}`);
+    }
+    // ------------------------------------------------------------- languages
+    line();
+    line('## Observed Languages');
+    line();
+    const languages = ofKind(facts, 'LANGUAGE_BY_EXTENSION');
+    if (languages.length === 0)
+        line('- No language-by-extension observations were recorded.');
+    for (const f of languages) {
+        const count = Number(f.value);
+        const full = sourceCoverage(f) === 'FULL';
+        line(`- ${code(f.subject)} (extension ${code(f.object)}): ${plural(count, 'observed file', 'observed files')}; source coverage ${full ? 'FULL' : 'SAMPLE'}`);
+        line(full ? `  - Sources (all ${plural(f.sources.length, 'file', 'files')}):` : `  - Source examples (${f.sources.length} listed of ${count} observed files; not a complete list):`);
+        for (const s of f.sources)
+            line(`    - ${sourceText(s)}`);
+    }
+    if (languages.length > 0) {
+        line();
+        line('- Language is derived from the file extension only; file contents were not inspected.');
+        if (partial)
+            line('- The result is PARTIAL: counts are lower bounds and some languages may be missing.');
+    }
+    if (stats.filesWithoutKnownLanguage > 0) {
+        if (languages.length === 0)
+            line();
+        line(`- ${plural(stats.filesWithoutKnownLanguage, 'file has', 'files have')} an extension with no known language mapping (reported, not guessed).`);
+    }
+    // ------------------------------------------------------------- manifests
+    line();
+    line('## Detected Manifests');
+    line();
+    const manifests = ofKind(facts, 'MANIFEST_PRESENT');
+    if (manifests.length === 0)
+        line('- No known manifest file names were observed.');
+    for (const f of manifests) {
+        const analysed = f.subject.slice(f.subject.lastIndexOf('/') + 1) === 'package.json';
+        line(`- ${code(f.subject)} (ecosystem hint ${code(f.object ?? '')}): file name observed; ${analysed ? 'content analysis is supported for this format; whether it was read is shown by the diagnostics' : 'content not analysed in this version'}`);
+    }
+    // ---------------------------------------------------------- dependencies
+    line();
+    line('## Declared Dependencies');
+    line();
+    const dependencies = ofKind(facts, 'DEPENDENCY_DECLARED');
+    if (dependencies.length === 0)
+        line('- No dependency declarations were observed.');
+    else {
+        line('- These are names declared in a manifest. They are not resolved, not installed and not checked against use in the code.');
+        for (const [manifest, group] of bySubject(dependencies)) {
+            line(`- Declared in ${code(manifest)}:`);
+            for (const section of DEPENDENCY_SECTIONS) {
+                const inSection = group.filter((f) => f.value === section);
+                if (inSection.length === 0)
+                    continue;
+                line(`  - ${code(section)} (${inSection.length}):`);
+                for (const f of inSection)
+                    line(`    - ${code(f.object)} — ${sourceText(f.sources[0])}`);
+            }
+        }
+    }
+    // --------------------------------------------------------------- scripts
+    line();
+    line('## Declared Scripts');
+    line();
+    const scripts = ofKind(facts, 'SCRIPT_DECLARED');
+    if (scripts.length === 0)
+        line('- No script declarations were observed.');
+    else {
+        line('- Only script names are recorded. Commands are neither stored nor run.');
+        for (const [manifest, group] of bySubject(scripts)) {
+            line(`- Declared in ${code(manifest)} (${group.length}):`);
+            for (const f of group)
+                line(`  - ${code(f.object)} — ${sourceText(f.sources[0])}`);
+        }
+    }
+    // ----------------------------------------------------------- entrypoints
+    line();
+    line('## Entrypoint Candidates');
+    line();
+    const entrypoints = ofKind(facts, 'ENTRYPOINT_CANDIDATE');
+    if (entrypoints.length === 0)
+        line('- No entrypoint candidates were observed.');
+    else {
+        line('- A candidate is a file whose name follows a common convention. It is not confirmed to start the program.');
+        for (const f of entrypoints)
+            line(`  - Candidate: ${code(f.subject)} (interpreted by rule ${code(f.rule)} from a file observed at this path)`);
+    }
+    // -------------------------------------------------------------- evidence
+    line();
+    line('## Evidence & Provenance');
+    line();
+    line('- Fact counts by kind:');
+    for (const kind of KIND_ORDER) {
+        const note = kind === 'FILE_PRESENT' ? ' (file evidence for entrypoint candidates only; not a count of project files)' : '';
+        line(`  - ${kind} (${FACT_LEVEL_BY_KIND[kind]}): ${ofKind(facts, kind).length}${note}`);
+    }
+    const sampled = languages.filter((f) => sourceCoverage(f) === 'SAMPLE').length;
+    line(`- Source coverage: ${plural(languages.length - sampled, 'aggregate is', 'aggregates are')} FULL and ${plural(sampled, 'aggregate is', 'aggregates are')} SAMPLE. Every other fact rests on exactly the source listed with it.`);
+    line('- DETECTED: observed in the project’s file names, directory entries or manifest fields. INTERPRETED: derived from DETECTED facts by a named rule.');
+    line('- Source paths are project-relative as reported by the result; none was checked again while rendering.');
+    // ----------------------------------------------------------- limitations
+    line();
+    line('## Limitations');
+    line();
+    line('- Not observing something is not evidence that it does not exist in the project.');
+    line('- Only package.json content is analysed; other manifest formats and documentation are not.');
+    line('- Dependencies and scripts are declarations; entrypoints are name-based candidates.');
+    line(`- Configured limits: ${Object.keys(LIMIT_LABELS).map((k) => `${LIMIT_LABELS[k]} ${limits[k]}`).join('; ')}.`);
+    line();
+    line('### Diagnostics');
+    line();
+    if (diagnostics.length === 0)
+        line('- No diagnostics were reported.');
+    for (const d of diagnostics)
+        line(diagnosticLine(d));
+    return `${out.join('\n')}\n`;
+}
+/** Internal (DISCOVERY-001C): the one safe way to place an untrusted string in Markdown, shared with the composer. */
+export { code as markdownCodeSpan };

package/dist/discovery/traverse.d.ts

@@ -0,0 +1,197 @@
+/**
+ * Bounded, safe project traversal (DISCOVERY-001B-1, ADR-021).
+ *
+ * Lists the directory tree of a project and nothing else: it never reads file
+ * content, never writes, never runs project code and never touches the network.
+ * It is the only code in Discovery that lists directories.
+ *
+ * What it does:
+ *  - lists each directory through `opendir` + `Dir#readSync` (never `readdirSync`),
+ *    one open handle at a time, so a hostile directory cannot be loaded whole before
+ *    a cap applies; the handle is always closed (`finally`);
+ *  - never follows a symlink (it is listed as kind `symlink` and counted; its target is
+ *    never looked at); FIFOs, sockets and devices are listed as `other`, never opened;
+ *  - excludes the real `<monolithRoot>` (resolved with `resolveMonolithRoot`, not by
+ *    the literal name `.monolith`), a fixed list of dependency/build directories, nested
+ *    repositories (a directory holding `.git`) and directories on another file system;
+ *  - bounds the work and the retained result: directory entries READ (every listing counts,
+ *    including the one of a directory later found to be unreadable, replaced or opaque),
+ *    entries per directory, depth, wall-clock time and the UTF-8 bytes of the retained
+ *    paths; every bound that fires yields `PARTIAL` with a typed diagnostic, never a
+ *    silent cut. A nested repository is recognised by one `lstat` of `<dir>/.git` BEFORE
+ *    the directory is listed, so its content is neither read nor counted;
+ *  - is deterministic for an unchanged tree: names are ordered by UTF-16 code units
+ *    (never `localeCompare`), breadth-first, and the result is sorted before it is
+ *    returned. No clock value, absolute path or `readdir` order reaches the result.
+ *
+ * What it does NOT do (ADR-013, SEC-001B.3 open; TM-C unsupported): it does not prevent
+ * and does not reliably detect a process that replaces a directory (e.g. with a symlink)
+ * while the walk runs. The window runs from the `lstat` that queues a directory until
+ * the walk has listed it, i.e. the breadth-first distance in between. Comparing the
+ * identity (`dev`/`ino`) of a directory before and after listing it (`DIR_CHANGED`) may
+ * notice SOME replacements; a replacement that is put back before the second `lstat`
+ * goes unnoticed, and names read from the substitute can then appear as COMPLETE.
+ * Do not run it on a tree an untrusted process is modifying.
+ *
+ * Root: `projectRoot` must be absolute and is the caller's explicit choice. A symlink as
+ * root is accepted and its target is walked (nothing below the root is ever followed, so
+ * the boundary is the directory the caller named). A missing, non-directory, unreadable
+ * or otherwise unresolvable root throws `ROOT_UNSAFE` (from `resolveMonolithRoot`, before
+ * any listing); `ROOT_NOT_DIRECTORY` is the defensive second check. Errors other than a
+ * root-containment error from `resolveMonolithRoot` propagate unchanged.
+ *
+ * Nested MONOLITH instances: only the actual `<monolithRoot>` is excluded. A sub-project
+ * that has its own `.monolith` stays part of the inventory (its sources belong to this
+ * project); that directory is not recognised by name. Excluding the confirmed internals
+ * of nested instances is a decision for DISCOVERY-001B-2.
+ *
+ * The time budget is checked between entries; a synchronous syscall that hangs in the
+ * kernel (e.g. a dead network mount) is not interrupted.
+ */
+import { type Dirent } from 'fs';
+export type TraversalEntryKind = 'file' | 'directory' | 'symlink' | 'other';
+export interface TraversalEntry {
+    /** Project-relative, `/`-separated; never absolute, never contains `..`. */
+    path: string;
+    kind: TraversalEntryKind;
+}
+export interface TraversalLimits {
+    /**
+     * Directory entries READ from the file system in total, across every listing (included in
+     * the result or not); see `LIMIT_ENTRIES`. A listing is charged for the entries it read,
+     * so a directory that does not fit in the remaining budget is not enumerated.
+     */
+    maxEntries: number;
+    /** A directory with more entries than this is opaque (not enumerated). */
+    maxEntriesPerDir: number;
+    /** Deepest path (in segments) that is listed; a directory at this depth is not entered. */
+    maxDepth: number;
+    /** Wall-clock budget in milliseconds (monotonic). */
+    deadlineMs: number;
+    /**
+     * Total UTF-8 bytes of the paths kept in `entries` (`Buffer.byteLength`, checked before an
+     * entry is added; see `LIMIT_PATH_BYTES`). It bounds the retained path text, not the memory
+     * of the process: JS strings, entry objects and the queue add overhead proportional to
+     * `maxEntries`, and the figure is a proxy for heap use (about one byte per ASCII character).
+     */
+    maxPathBytes: number;
+}
+/** Starting values (ADR-021 Q-10); validated by the 001B-1 benchmark, see the story report. */
+export declare const DEFAULT_TRAVERSAL_LIMITS: Readonly<TraversalLimits>;
+/** Directories never entered, matched by name at any depth. */
+export declare const EXCLUDED_DIR_NAMES: readonly string[];
+/** Directories never entered, matched by project-relative path. */
+export declare const EXCLUDED_DIR_PATHS: readonly string[];
+/**
+ * Closed list. `affectsCompleteness` codes make the result PARTIAL (something inside
+ * the declared scope could not be done). The others report the scope policy.
+ * An unknown code is treated as affecting completeness (fail closed).
+ */
+declare const DIAGNOSTIC_AFFECTS_COMPLETENESS: {
+    readonly LIMIT_ENTRIES: true;
+    readonly LIMIT_DEPTH: true;
+    readonly LIMIT_DIR_ENTRIES: true;
+    readonly LIMIT_DEADLINE: true;
+    readonly LIMIT_PATH_BYTES: true;
+    readonly DIR_UNREADABLE: true;
+    readonly DIR_VANISHED: true;
+    readonly DIR_CHANGED: true;
+    readonly DIR_ERROR: true;
+    readonly NAME_UNREPRESENTABLE: true;
+    readonly ENTRY_UNCLASSIFIED: true;
+    readonly EXCLUDED_DIR: false;
+    readonly MONOLITH_ROOT_EXCLUDED: false;
+    readonly SYMLINK_SKIPPED: false;
+    readonly NESTED_REPO_SKIPPED: false;
+    readonly MOUNT_SKIPPED: false;
+};
+export type TraversalDiagnosticCode = keyof typeof DIAGNOSTIC_AFFECTS_COMPLETENESS;
+export interface TraversalDiagnostic {
+    code: TraversalDiagnosticCode;
+    /** Project-relative path, when the diagnostic concerns one. */
+    path?: string;
+    /** Total occurrences, present on the summary line of a code that exceeded the listed paths. */
+    count?: number;
+    message: string;
+}
+export interface TraversalStats {
+    /** Entries included in `entries`. */
+    entries: number;
+    files: number;
+    directories: number;
+    symlinks: number;
+    other: number;
+    /** Directory entries read from the file system by all listings (the figure `maxEntries` bounds). */
+    examined: number;
+    /** UTF-8 bytes of the paths in `entries` (the figure `maxPathBytes` bounds). */
+    pathBytes: number;
+    /** Directories whose contents were listed. */
+    listedDirectories: number;
+}
+export interface TraversalResult {
+    /** `PARTIAL` as soon as something inside the declared scope could not be done. */
+    completeness: 'COMPLETE' | 'PARTIAL';
+    /**
+     * `true` when a second walk of the same, unchanged tree with the same limits would return
+     * this exact result. It is `false` when any diagnostic whose cause is not a function of the
+     * tree alone was recorded: the time budget (`LIMIT_DEADLINE`), a tree that changed or a
+     * transient failure (`DIR_CHANGED`, `DIR_VANISHED`, `DIR_ERROR`) or an entry whose type
+     * could not be determined (`ENTRY_UNCLASSIFIED`). It is not a synonym of `COMPLETE`: a
+     * walk cut by a deterministic limit is `PARTIAL` and still reproducible. It is a statement
+     * about the result, not a guarantee about a tree that changes during the walk.
+     */
+    reproducible: boolean;
+    limits: TraversalLimits;
+    stats: TraversalStats;
+    /** Sorted by `path` in UTF-16 code-unit order. */
+    entries: TraversalEntry[];
+    /** Sorted: completeness-affecting first, then by code, path, message. */
+    diagnostics: TraversalDiagnostic[];
+}
+export type TraversalErrorCode = 'INVALID_LIMITS' | 'ROOT_UNSAFE' | 'ROOT_NOT_DIRECTORY' | 'UNSUPPORTED_PLATFORM';
+/** The traversal cannot start or cannot be trusted; no result exists (FAILED). */
+export declare class TraversalError extends Error {
+    readonly code: TraversalErrorCode;
+    constructor(code: TraversalErrorCode, message: string, options?: {
+        cause?: unknown;
+    });
+}
+export interface TraversalDirHandle {
+    readSync(): Dirent | null;
+    closeSync(): void;
+}
+export interface TraversalIdentity {
+    isFile(): boolean;
+    isDirectory(): boolean;
+    isSymbolicLink(): boolean;
+    dev: bigint;
+    ino: bigint;
+}
+export interface TraversalFs {
+    opendir(path: string): TraversalDirHandle;
+    lstat(path: string): TraversalIdentity;
+    stat(path: string): TraversalIdentity;
+}
+export interface TraverseOptions {
+    limits?: Partial<TraversalLimits>;
+    /** @internal Test seam. */
+    fs?: TraversalFs;
+    /** @internal Test seam: monotonic milliseconds. */
+    now?: () => number;
+    /** @internal Test seam: the `open(2)` flags the platform provides. */
+    platformFlags?: {
+        noFollow?: number;
+        nonBlock?: number;
+    };
+}
+/**
+ * Walk the project at `projectRoot` and return its structure.
+ *
+ * `projectRoot` is the explicit, caller-resolved project directory (for the CLI: `cwd`).
+ * The instance root is resolved with `resolveMonolithRoot` and excluded. Throws
+ * `TraversalError` when the walk cannot start or be trusted; otherwise returns a
+ * result that says whether it is `COMPLETE` or `PARTIAL`.
+ */
+export declare function traverseProject(projectRoot: string, options?: TraverseOptions): TraversalResult;
+export {};
+//# sourceMappingURL=traverse.d.ts.map

package/dist/discovery/traverse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"traverse.d.ts","sourceRoot":"","sources":["../../src/discovery/traverse.ts"],"names":[],"mappings":"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"}