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

package/dist/discovery/facts.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Deterministic structural fact extraction (DISCOVERY-001B-2, ADR-021).
+ *
+ * Input: a `TraversalResult` (what exists). Output: a `DiscoveryResult` (facts with sources).
+ * It states what the files show and nothing about what the project is: no component roles,
+ * no verified entrypoints, no "main language", no installed or resolved dependencies.
+ *
+ * Reading: the only content read is `package.json` (at most `maxManifestReads` of them, at most
+ * `maxManifestBytes` each), through `readProjectFile` (ADR-011/014: every component below the project
+ * root is `lstat`-checked and none may be a symlink, `O_NOFOLLOW|O_NONBLOCK`, regular single-link
+ * file, bounded read). The traversal having listed a path proves nothing about the next read, so
+ * every read is made on its own terms. It only extracts JSON via `JSON.parse`; it never evaluates,
+ * runs or imports project code, never uses a subprocess or the network.
+ * `scripts` values and dependency version specifiers are never read into a fact.
+ * TOML/YAML manifests are recognised by name and not parsed (no home-made parsers).
+ *
+ * NOT defended (ADR-013, SEC-001B.3 open; TM-C unsupported): a process that swaps a directory or
+ * file between the check and the open. Do not run it on a tree an untrusted process is modifying.
+ *
+ * Nested MONOLITH: a sub-project's source is part of this project. A directory named `.monolith`
+ * (other than the real root, which the traversal already excluded) is treated as that sub-project's
+ * internal state only when its content proves it (`state.json` plus `memory/` or `context/` in the
+ * inventory); then its entries are left out of the facts. A bare name proves nothing: the directory
+ * stays in and a diagnostic says it is unconfirmed. A nested instance whose root is renamed through
+ * its own config is not recognised (that needs reading foreign config: a separate decision).
+ *
+ * Determinism: every input is sorted by UTF-16 code units before use, so the order of
+ * `traversal.entries` cannot change the result; no clock, absolute path or host value is read.
+ */
+import { type ProjectFileRead } from '../root/index.js';
+import type { TraversalResult } from './traverse.js';
+import { type DiscoveryLimits, type DiscoveryResult } from './contracts.js';
+export declare const DEFAULT_DISCOVERY_LIMITS: Readonly<DiscoveryLimits>;
+/** Extension (lower case, with the dot) to language. Evidence is the extension and nothing else. */
+export declare const LANGUAGE_BY_EXTENSION: Readonly<Record<string, string>>;
+/** Known manifest file name to the ecosystem its presence points at (a presence, not a runtime use). */
+export declare const KNOWN_MANIFESTS: Readonly<Record<string, string>>;
+/** Project-relative file names that may start a program. Only candidates, ever. */
+export declare const ENTRYPOINT_CANDIDATE_PATHS: readonly string[];
+export type ManifestReader = (projectRoot: string, relPath: string, opts: {
+    maxBytes: number;
+}) => ProjectFileRead;
+export interface ExtractOptions {
+    limits?: Partial<DiscoveryLimits>;
+    /** @internal Test seam; production uses `readProjectFile`. */
+    readManifest?: ManifestReader;
+}
+export declare function extractProjectFacts(projectRoot: string, traversal: TraversalResult, options?: ExtractOptions): DiscoveryResult;
+//# sourceMappingURL=facts.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"facts.d.ts","sourceRoot":"","sources":["../../src/discovery/facts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAGH,OAAO,EAA8C,KAAK,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACpG,OAAO,KAAK,EAAkB,eAAe,EAAE,MAAM,eAAe,CAAC;AACrE,OAAO,EAmBL,KAAK,eAAe,EACpB,KAAK,eAAe,EAGrB,MAAM,gBAAgB,CAAC;AAExB,eAAO,MAAM,wBAAwB,EAAE,QAAQ,CAAC,eAAe,CAc7D,CAAC;AAEH,oGAAoG;AACpG,eAAO,MAAM,qBAAqB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAwBjE,CAAC;AAEH,wGAAwG;AACxG,eAAO,MAAM,eAAe,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAO3D,CAAC;AAEH,mFAAmF;AACnF,eAAO,MAAM,0BAA0B,EAAE,SAAS,MAAM,EAwBvD,CAAC;AAIF,MAAM,MAAM,cAAc,GAAG,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,KAAK,eAAe,CAAC;AAEnH,MAAM,WAAW,cAAc;IAC7B,MAAM,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,CAAC;IAClC,8DAA8D;IAC9D,YAAY,CAAC,EAAE,cAAc,CAAC;CAC/B;AAyOD,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,MAAM,EAAE,SAAS,EAAE,eAAe,EAAE,OAAO,GAAE,cAAmB,GAAG,eAAe,CAwNlI"}

package/dist/discovery/facts.js

@@ -0,0 +1,541 @@
+/**
+ * Deterministic structural fact extraction (DISCOVERY-001B-2, ADR-021).
+ *
+ * Input: a `TraversalResult` (what exists). Output: a `DiscoveryResult` (facts with sources).
+ * It states what the files show and nothing about what the project is: no component roles,
+ * no verified entrypoints, no "main language", no installed or resolved dependencies.
+ *
+ * Reading: the only content read is `package.json` (at most `maxManifestReads` of them, at most
+ * `maxManifestBytes` each), through `readProjectFile` (ADR-011/014: every component below the project
+ * root is `lstat`-checked and none may be a symlink, `O_NOFOLLOW|O_NONBLOCK`, regular single-link
+ * file, bounded read). The traversal having listed a path proves nothing about the next read, so
+ * every read is made on its own terms. It only extracts JSON via `JSON.parse`; it never evaluates,
+ * runs or imports project code, never uses a subprocess or the network.
+ * `scripts` values and dependency version specifiers are never read into a fact.
+ * TOML/YAML manifests are recognised by name and not parsed (no home-made parsers).
+ *
+ * NOT defended (ADR-013, SEC-001B.3 open; TM-C unsupported): a process that swaps a directory or
+ * file between the check and the open. Do not run it on a tree an untrusted process is modifying.
+ *
+ * Nested MONOLITH: a sub-project's source is part of this project. A directory named `.monolith`
+ * (other than the real root, which the traversal already excluded) is treated as that sub-project's
+ * internal state only when its content proves it (`state.json` plus `memory/` or `context/` in the
+ * inventory); then its entries are left out of the facts. A bare name proves nothing: the directory
+ * stays in and a diagnostic says it is unconfirmed. A nested instance whose root is renamed through
+ * its own config is not recognised (that needs reading foreign config: a separate decision).
+ *
+ * Determinism: every input is sorted by UTF-16 code units before use, so the order of
+ * `traversal.entries` cannot change the result; no clock, absolute path or host value is read.
+ */
+import { isAbsolute } from 'path';
+import { readProjectFile } from '../root/index.js';
+import { DEPENDENCY_SECTIONS, DISCOVERY_SCHEMA_VERSION, DiscoveryError, EXTRACTION_DIAGNOSTIC_AFFECTS_COMPLETENESS, EXTRACTION_DIAGNOSTIC_IS_STABLE, FACT_LEVEL_BY_KIND, compareDiagnostics, compareFacts, compareSources, compareUtf16, computeFactId, isKeepableName, isSafeRelativePath, pointerToken, validateDiscoveryResult, } from './contracts.js';
+export const DEFAULT_DISCOVERY_LIMITS = Object.freeze({
+    maxDirectoryFacts: 200,
+    maxDirectoryDepth: 2,
+    maxLanguageFacts: 64,
+    maxManifestFacts: 50,
+    maxManifestReads: 20,
+    maxManifestBytes: 256 * 1024,
+    maxDependenciesPerManifest: 500,
+    maxScriptsPerManifest: 100,
+    maxEntrypointFacts: 20,
+    maxFacts: 5000,
+    maxDiagnostics: 200,
+    maxNameLength: 214,
+    maxSourcesPerFact: 3,
+});
+/** Extension (lower case, with the dot) to language. Evidence is the extension and nothing else. */
+export const LANGUAGE_BY_EXTENSION = Object.freeze({
+    '.ts': 'TypeScript',
+    '.tsx': 'TypeScript',
+    '.mts': 'TypeScript',
+    '.cts': 'TypeScript',
+    '.js': 'JavaScript',
+    '.jsx': 'JavaScript',
+    '.mjs': 'JavaScript',
+    '.cjs': 'JavaScript',
+    '.py': 'Python',
+    '.rs': 'Rust',
+    '.go': 'Go',
+    '.java': 'Java',
+    '.kt': 'Kotlin',
+    '.rb': 'Ruby',
+    '.php': 'PHP',
+    '.cs': 'C#',
+    '.c': 'C',
+    '.h': 'C',
+    '.cc': 'C++',
+    '.cpp': 'C++',
+    '.hpp': 'C++',
+    '.swift': 'Swift',
+    '.vue': 'Vue',
+});
+/** Known manifest file name to the ecosystem its presence points at (a presence, not a runtime use). */
+export const KNOWN_MANIFESTS = Object.freeze({
+    'package.json': 'npm',
+    'pnpm-workspace.yaml': 'pnpm',
+    'pyproject.toml': 'python',
+    'requirements.txt': 'pip',
+    'Cargo.toml': 'cargo',
+    'go.mod': 'go',
+});
+/** Project-relative file names that may start a program. Only candidates, ever. */
+export const ENTRYPOINT_CANDIDATE_PATHS = [
+    'index.js',
+    'index.ts',
+    'main.js',
+    'main.ts',
+    'server.js',
+    'server.ts',
+    'app.js',
+    'app.ts',
+    'src/index.js',
+    'src/index.ts',
+    'src/main.js',
+    'src/main.ts',
+    'src/server.js',
+    'src/server.ts',
+    'src/app.js',
+    'src/app.ts',
+    'app.py',
+    'main.py',
+    'manage.py',
+    'src/app.py',
+    'src/main.py',
+    'main.go',
+    'src/main.rs',
+];
+const LIMIT_KEYS = Object.keys(DEFAULT_DISCOVERY_LIMITS);
+function resolveLimits(partial) {
+    const limits = { ...DEFAULT_DISCOVERY_LIMITS };
+    for (const [key, value] of Object.entries(partial ?? {})) {
+        if (!LIMIT_KEYS.includes(key))
+            throw new DiscoveryError('INVALID_LIMITS', `unknown limit "${key}".`);
+        if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 1) {
+            throw new DiscoveryError('INVALID_LIMITS', `limit "${key}" must be a positive integer.`);
+        }
+        limits[key] = value;
+    }
+    return limits;
+}
+// ---------------------------------------------------------------------------
+// Diagnostics
+// ---------------------------------------------------------------------------
+class Diagnostics {
+    list = [];
+    add(code, message, path, count) {
+        const d = { code, message };
+        if (path !== undefined)
+            d.path = path;
+        if (count !== undefined)
+            d.count = count;
+        this.list.push(d);
+    }
+    all() {
+        return this.list;
+    }
+}
+// ---------------------------------------------------------------------------
+// Fact sink: one place that builds ids, merges equal facts, enforces the global budget
+// ---------------------------------------------------------------------------
+class FactSink {
+    max;
+    byId = new Map();
+    dropped = 0;
+    constructor(max) {
+        this.max = max;
+    }
+    get size() {
+        return this.byId.size;
+    }
+    /** Adds facts as one unit (an interpretation and its basis stay together); false when the budget refuses. */
+    addAll(specs) {
+        const ids = specs.map((s) => computeFactId(s.kind, s.subject, s.object, s.value));
+        const added = new Set(ids.filter((id) => !this.byId.has(id)));
+        if (this.byId.size + added.size > this.max) {
+            this.dropped += specs.length;
+            return false;
+        }
+        for (const s of specs)
+            this.put(s);
+        return true;
+    }
+    put(s) {
+        const id = computeFactId(s.kind, s.subject, s.object, s.value);
+        const existing = this.byId.get(id);
+        if (existing) {
+            if (existing.kind !== s.kind || existing.subject !== s.subject || existing.object !== s.object || existing.value !== s.value) {
+                throw new DiscoveryError('ID_COLLISION', `fact id ${id} is shared by two different facts.`);
+            }
+            const merged = new Map(existing.sources.map((x) => [JSON.stringify(x), x]));
+            for (const x of s.sources)
+                merged.set(JSON.stringify(x), x);
+            existing.sources = [...merged.values()].sort(compareSources);
+            return;
+        }
+        const fact = { id, kind: s.kind, level: FACT_LEVEL_BY_KIND[s.kind], subject: s.subject, rule: s.rule, sources: [...s.sources].sort(compareSources) };
+        if (s.object !== undefined)
+            fact.object = s.object;
+        if (s.value !== undefined)
+            fact.value = s.value;
+        if (s.basis)
+            fact.basis = [...s.basis].sort(compareUtf16);
+        this.byId.set(id, fact);
+    }
+    facts() {
+        return [...this.byId.values()].sort(compareFacts);
+    }
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+const depthOf = (p) => p.split('/').length;
+const baseName = (p) => p.slice(p.lastIndexOf('/') + 1);
+function extensionOf(path) {
+    const name = baseName(path);
+    const dot = name.lastIndexOf('.');
+    // `.gitignore`-style names and names ending in a dot have no extension.
+    if (dot <= 0 || dot === name.length - 1)
+        return undefined;
+    return name.slice(dot).toLowerCase();
+}
+function compareDepthThenPath(a, b) {
+    return depthOf(a) - depthOf(b) || compareUtf16(a, b);
+}
+function isPlainObject(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+/** Every code `readProjectFile` can return; anything else is reported as `UNKNOWN`. Exhaustive by type. */
+const READ_ERROR_CODES = new Set(Object.keys({
+    FILE_MISSING: 0,
+    FILE_OUTSIDE_PROJECT: 0,
+    FILE_UNRESOLVABLE: 0,
+    FILE_NOT_REGULAR: 0,
+    FILE_EMPTY: 0,
+    FILE_TOO_LARGE: 0,
+    FILE_CHANGED: 0,
+    FILE_UNREADABLE: 0,
+    FILE_SYMLINK: 0,
+    FILE_HARDLINKED: 0,
+    READ_BOUNDARY_INVALID: 0,
+    READ_UNSUPPORTED_PLATFORM: 0,
+}));
+function parsePackageJson(projectRoot, path, limits, read, diag) {
+    // The reader is a seam: whatever it returns or throws is untrusted. Only a code from the closed
+    // list below, a size-checked string and a fixed message can come out of this block.
+    let content;
+    try {
+        const r = read(projectRoot, path, { maxBytes: limits.maxManifestBytes });
+        if (r.ok) {
+            if (typeof r.content !== 'string')
+                throw new TypeError('content');
+            content = r.content;
+        }
+        else {
+            // `detail` may carry an absolute path or a system message: never read.
+            const code = READ_ERROR_CODES.has(r.code) ? r.code : 'UNKNOWN';
+            if (code === 'FILE_EMPTY')
+                diag.add('MANIFEST_EMPTY', 'the manifest is empty; nothing was extracted.', path);
+            else if (code === 'FILE_TOO_LARGE')
+                diag.add('MANIFEST_TOO_LARGE', `the manifest exceeds ${limits.maxManifestBytes} bytes and was not read.`, path);
+            else
+                diag.add('MANIFEST_READ_FAILED', `the manifest was refused or could not be read (${code}).`, path);
+            return undefined;
+        }
+    }
+    catch {
+        diag.add('MANIFEST_READ_FAILED', 'the manifest could not be read (unexpected failure).', path);
+        return undefined;
+    }
+    let doc;
+    try {
+        // JSON.parse only: no reviver, no evaluation. Its error text can quote the input, so it is dropped.
+        doc = JSON.parse(content.charCodeAt(0) === 0xfeff ? content.slice(1) : content);
+    }
+    catch {
+        diag.add('MANIFEST_PARSE_ERROR', 'the manifest is not valid JSON; nothing was extracted.', path);
+        return undefined;
+    }
+    if (!isPlainObject(doc)) {
+        diag.add('MANIFEST_FIELD_INVALID', 'the top-level JSON value is not an object; nothing was extracted.', path);
+        return undefined;
+    }
+    const section = (name) => {
+        if (!Object.prototype.hasOwnProperty.call(doc, name))
+            return undefined;
+        const v = doc[name];
+        if (!isPlainObject(v)) {
+            diag.add('MANIFEST_FIELD_INVALID', `field "${name}" is not an object and was ignored.`, path);
+            return undefined;
+        }
+        // Keys only. The values (version specifiers, commands) are never touched.
+        return Object.keys(v).sort(compareUtf16);
+    };
+    let rejected = 0;
+    const dependencies = [];
+    let droppedDeps = 0;
+    const seen = new Set();
+    for (const sec of DEPENDENCY_SECTIONS) {
+        for (const name of section(sec) ?? []) {
+            if (!isKeepableName(name, limits.maxNameLength)) {
+                rejected++;
+                continue;
+            }
+            const key = `${sec}\u0000${name}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            if (dependencies.length >= limits.maxDependenciesPerManifest)
+                droppedDeps++;
+            else
+                dependencies.push({ name, section: sec });
+        }
+    }
+    const scripts = [];
+    let droppedScripts = 0;
+    for (const name of section('scripts') ?? []) {
+        if (!isKeepableName(name, limits.maxNameLength)) {
+            rejected++;
+            continue;
+        }
+        if (scripts.length >= limits.maxScriptsPerManifest)
+            droppedScripts++;
+        else
+            scripts.push(name);
+    }
+    if (rejected > 0)
+        diag.add('MANIFEST_VALUE_REJECTED', 'names that are empty, too long or contain control, bidirectional or invalid characters were not kept.', path, rejected);
+    if (droppedDeps > 0)
+        diag.add('LIMIT_DEPENDENCIES', `dependency names beyond ${limits.maxDependenciesPerManifest} were not kept.`, path, droppedDeps);
+    if (droppedScripts > 0)
+        diag.add('LIMIT_SCRIPTS', `script names beyond ${limits.maxScriptsPerManifest} were not kept.`, path, droppedScripts);
+    return { path, dependencies, scripts };
+}
+// ---------------------------------------------------------------------------
+// Extraction
+// ---------------------------------------------------------------------------
+const ENTRY_KINDS = new Set(['file', 'directory', 'symlink', 'other']);
+export function extractProjectFacts(projectRoot, traversal, options = {}) {
+    if (typeof projectRoot !== 'string' || !isAbsolute(projectRoot)) {
+        throw new DiscoveryError('INVALID_INPUT', 'the project root must be an explicit absolute path.');
+    }
+    if (!traversal ||
+        !Array.isArray(traversal.entries) ||
+        !Array.isArray(traversal.diagnostics) ||
+        (traversal.completeness !== 'COMPLETE' && traversal.completeness !== 'PARTIAL') ||
+        typeof traversal.reproducible !== 'boolean') {
+        throw new DiscoveryError('INVALID_INPUT', 'the traversal result is malformed.');
+    }
+    const limits = resolveLimits(options.limits);
+    const read = options.readManifest ?? ((root, rel, o) => readProjectFile(root, rel, { maxBytes: o.maxBytes }));
+    const diag = new Diagnostics();
+    // 1. Input hygiene: a handcrafted or corrupted entry must not reach a path join or a fact.
+    let rejectedPaths = 0;
+    const kindByPath = new Map();
+    for (const e of traversal.entries) {
+        if (!e || !ENTRY_KINDS.has(e.kind) || !isSafeRelativePath(e.path)) {
+            rejectedPaths++;
+            continue;
+        }
+        // Duplicate path with another kind: the lexically smaller kind wins, independent of input order.
+        const prior = kindByPath.get(e.path);
+        if (prior === undefined || compareUtf16(e.kind, prior) < 0)
+            kindByPath.set(e.path, e.kind);
+    }
+    if (rejectedPaths > 0)
+        diag.add('INPUT_PATH_REJECTED', 'traversal entries with an unsafe path or an unknown kind were ignored.', undefined, rejectedPaths);
+    // 2. Nested MONOLITH state (confirmed by content only; a name alone proves nothing).
+    const nestedState = [];
+    for (const [path, kind] of [...kindByPath].sort((a, b) => compareUtf16(a[0], b[0]))) {
+        if (kind !== 'directory' || baseName(path) !== '.monolith')
+            continue;
+        const has = (rel, k) => kindByPath.get(`${path}/${rel}`) === k;
+        if (has('state.json', 'file') && (has('memory', 'directory') || has('context', 'directory'))) {
+            nestedState.push(path);
+            diag.add('NESTED_MONOLITH_STATE_EXCLUDED', 'a nested MONOLITH instance state directory (confirmed by its content) is not part of the facts.', path);
+        }
+        else {
+            diag.add('NESTED_MONOLITH_UNCONFIRMED', 'a directory named .monolith was found but its content does not confirm a MONOLITH instance; it is kept as ordinary content.', path);
+        }
+    }
+    const nestedSet = new Set(nestedState);
+    const insideNested = (path) => {
+        for (let i = path.indexOf('/');; i = path.indexOf('/', i + 1)) {
+            if (nestedSet.has(i === -1 ? path : path.slice(0, i)))
+                return true;
+            if (i === -1)
+                return false;
+        }
+    };
+    const kept = [...kindByPath].filter(([p]) => !insideNested(p)).sort((a, b) => compareUtf16(a[0], b[0]));
+    const excludedEntries = traversal.entries.length - kept.length;
+    const files = kept.filter(([, k]) => k === 'file').map(([p]) => p);
+    const sink = new FactSink(limits.maxFacts);
+    // 3. Manifests: presence (by name) is separated from content (read below).
+    const manifestCandidates = [];
+    for (const [path, kind] of kept) {
+        if (!Object.prototype.hasOwnProperty.call(KNOWN_MANIFESTS, baseName(path)))
+            continue;
+        if (kind === 'file')
+            manifestCandidates.push(path);
+        else if (kind === 'symlink' || kind === 'other')
+            diag.add('MANIFEST_NOT_REGULAR_FILE', `an entry with the name of a known manifest is not a regular file (${kind}); it was not treated as a manifest.`, path);
+    }
+    manifestCandidates.sort(compareDepthThenPath);
+    const manifests = manifestCandidates.slice(0, limits.maxManifestFacts);
+    if (manifestCandidates.length > manifests.length) {
+        diag.add('LIMIT_MANIFEST_FACTS', `manifests beyond ${limits.maxManifestFacts} (deepest last) were not recorded.`, undefined, manifestCandidates.length - manifests.length);
+    }
+    // 4. Entrypoint candidates (INTERPRETED) rest on a DETECTED file fact.
+    const present = new Set(files);
+    const candidates = ENTRYPOINT_CANDIDATE_PATHS.filter((p) => present.has(p)).sort(compareUtf16);
+    const candidateSpecs = candidates.slice(0, limits.maxEntrypointFacts);
+    if (candidates.length > candidateSpecs.length) {
+        diag.add('LIMIT_ENTRYPOINT_FACTS', `entrypoint candidates beyond ${limits.maxEntrypointFacts} were not recorded.`, undefined, candidates.length - candidateSpecs.length);
+    }
+    // 5. Languages by extension.
+    const groups = new Map();
+    let withoutLanguage = 0;
+    for (const path of files) {
+        const ext = extensionOf(path);
+        const language = ext !== undefined && Object.prototype.hasOwnProperty.call(LANGUAGE_BY_EXTENSION, ext) ? LANGUAGE_BY_EXTENSION[ext] : undefined;
+        if (ext === undefined || language === undefined) {
+            withoutLanguage++;
+            continue;
+        }
+        const g = groups.get(ext) ?? { language, ext, paths: [] };
+        g.paths.push(path);
+        groups.set(ext, g);
+    }
+    const languageGroups = [...groups.values()].sort((a, b) => compareUtf16(a.language, b.language) || compareUtf16(a.ext, b.ext));
+    // 6. Directories (shallow, bounded).
+    const dirs = kept
+        .filter(([p, k]) => k === 'directory' && depthOf(p) <= limits.maxDirectoryDepth)
+        .map(([p]) => p)
+        .sort(compareDepthThenPath);
+    // 7. Manifest content: package.json only, bounded in count and size.
+    const packageJsons = manifests.filter((p) => baseName(p) === 'package.json');
+    const toRead = packageJsons.slice(0, limits.maxManifestReads);
+    if (packageJsons.length > toRead.length) {
+        diag.add('LIMIT_MANIFEST_READS', `package.json files beyond ${limits.maxManifestReads} were recorded as present but not read.`, undefined, packageJsons.length - toRead.length);
+    }
+    const parsed = [];
+    for (const p of toRead) {
+        const m = parsePackageJson(projectRoot, p, limits, read, diag);
+        if (m)
+            parsed.push(m);
+    }
+    const unparsedNames = new Map();
+    for (const p of manifests) {
+        const name = baseName(p);
+        if (name !== 'package.json')
+            unparsedNames.set(name, (unparsedNames.get(name) ?? 0) + 1);
+    }
+    for (const [name, count] of [...unparsedNames].sort((a, b) => compareUtf16(a[0], b[0]))) {
+        diag.add('MANIFEST_CONTENT_NOT_ANALYZED', `${name}: recorded as present; its content is not analyzed in this version.`, undefined, count);
+    }
+    // 8. Emit in priority order, so the global budget (`maxFacts`) cuts the bulkiest, least structural
+    //    facts (dependency names) first and deterministically.
+    const emit = (kind, subject, rule, source, extra = {}) => ({
+        kind,
+        subject,
+        rule,
+        sources: [source],
+        ...extra,
+    });
+    for (const p of manifests) {
+        sink.addAll([emit('MANIFEST_PRESENT', p, 'known-manifest-file-name', { path: p, observation: 'file-name' }, { object: KNOWN_MANIFESTS[baseName(p)] })]);
+    }
+    for (const p of candidateSpecs) {
+        const fileId = computeFactId('FILE_PRESENT', p);
+        sink.addAll([
+            emit('FILE_PRESENT', p, 'conventional-file-name', { path: p, observation: 'file-entry' }),
+            emit('ENTRYPOINT_CANDIDATE', p, 'entrypoint-convention', { path: p, observation: 'file-name' }, { value: 'candidate', basis: [fileId] }),
+        ]);
+    }
+    let languageDropped = 0;
+    languageGroups.forEach((g, i) => {
+        if (i >= limits.maxLanguageFacts) {
+            languageDropped++;
+            return;
+        }
+        // `value` counts every file of the group; the sources are the first few in UTF-16 order (a sample).
+        const example = g.paths.slice(0, limits.maxSourcesPerFact);
+        sink.addAll([
+            {
+                kind: 'LANGUAGE_BY_EXTENSION',
+                subject: g.language,
+                object: g.ext,
+                value: String(g.paths.length),
+                rule: 'extension-map',
+                sources: example.map((path) => ({ path, observation: 'extension' })),
+            },
+        ]);
+    });
+    if (languageDropped > 0)
+        diag.add('LIMIT_LANGUAGE_FACTS', `language facts beyond ${limits.maxLanguageFacts} were not recorded.`, undefined, languageDropped);
+    const dirsKept = dirs.slice(0, limits.maxDirectoryFacts);
+    for (const p of dirsKept)
+        sink.addAll([emit('DIRECTORY', p, 'walk-directory', { path: p, observation: 'directory-entry' })]);
+    if (dirs.length > dirsKept.length)
+        diag.add('LIMIT_DIRECTORY_FACTS', `directories beyond ${limits.maxDirectoryFacts} (deepest last) were not recorded.`, undefined, dirs.length - dirsKept.length);
+    for (const m of parsed) {
+        for (const name of m.scripts) {
+            sink.addAll([emit('SCRIPT_DECLARED', m.path, 'package-json-scripts', { path: m.path, observation: 'manifest-field', field: `/scripts/${pointerToken(name)}` }, { object: name })]);
+        }
+    }
+    for (const m of parsed) {
+        for (const d of m.dependencies) {
+            sink.addAll([
+                emit('DEPENDENCY_DECLARED', m.path, `package-json-${d.section}`, { path: m.path, observation: 'manifest-field', field: `/${d.section}/${pointerToken(d.name)}` }, { object: d.name, value: d.section }),
+            ]);
+        }
+    }
+    if (sink.dropped > 0)
+        diag.add('LIMIT_FACTS', `facts beyond ${limits.maxFacts} were not recorded (dependency and script names are cut first).`, undefined, sink.dropped);
+    // 9. Diagnostics: extraction first (completeness-affecting before the rest), then the traversal's.
+    const fromTraversal = traversal.diagnostics.map((d) => {
+        const out = { code: `TRAVERSAL_${String(d.code)}`, message: String(d.message) };
+        if (d.path !== undefined && isSafeRelativePath(d.path))
+            out.path = d.path;
+        if (d.count !== undefined)
+            out.count = d.count;
+        return out;
+    });
+    let diagnostics = [...diag.all(), ...fromTraversal].sort(compareDiagnostics);
+    let diagnosticsDropped = 0;
+    if (diagnostics.length > limits.maxDiagnostics) {
+        diagnosticsDropped = diagnostics.length - (limits.maxDiagnostics - 1);
+        diagnostics = diagnostics.slice(0, limits.maxDiagnostics - 1);
+        diagnostics.unshift({ code: 'LIMIT_DIAGNOSTICS', count: diagnosticsDropped, message: `${diagnosticsDropped} diagnostics beyond the limit of ${limits.maxDiagnostics} were not kept.` });
+    }
+    // 10. Completeness, reproducibility: separate properties.
+    const extractionCodes = [...diag.all()].map((d) => d.code);
+    if (diagnosticsDropped > 0)
+        extractionCodes.push('LIMIT_DIAGNOSTICS');
+    const partial = traversal.completeness === 'PARTIAL' || extractionCodes.some((c) => EXTRACTION_DIAGNOSTIC_AFFECTS_COMPLETENESS[c]);
+    const reproducible = traversal.reproducible && extractionCodes.every((c) => EXTRACTION_DIAGNOSTIC_IS_STABLE[c]);
+    const facts = sink.facts();
+    const result = {
+        schemaVersion: DISCOVERY_SCHEMA_VERSION,
+        limits,
+        completeness: partial ? 'PARTIAL' : 'COMPLETE',
+        reproducible,
+        traversal: { completeness: traversal.completeness, reproducible: traversal.reproducible },
+        stats: {
+            inputEntries: traversal.entries.length,
+            excludedEntries,
+            filesWithoutKnownLanguage: withoutLanguage,
+            manifestsFound: manifestCandidates.length,
+            manifestsRead: toRead.length,
+            facts: facts.length,
+        },
+        facts,
+        diagnostics,
+    };
+    const violations = validateDiscoveryResult(result);
+    if (violations.length > 0)
+        throw new DiscoveryError('RESULT_INVALID', `the result failed validation: ${violations.slice(0, 3).join('; ')}`);
+    return result;
+}

package/dist/discovery/index.d.ts

@@ -0,0 +1,8 @@
+export * from './traverse.js';
+export * from './contracts.js';
+export * from './facts.js';
+export * from './render.js';
+export * from './docs.js';
+export * from './compose.js';
+export * from './orchestrate.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/discovery/index.ts"],"names":[],"mappings":"AAEA,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,cAAc,CAAC;AAC7B,cAAc,kBAAkB,CAAC"}

package/dist/discovery/index.js

@@ -0,0 +1,9 @@
+// Discovery (ADR-021). Internal module: deliberately NOT exported from `src/index.ts`
+// until the owner decides (ADR-021 Q-7). DISCOVERY-001B-1: safe traversal; 001B-2: fact extraction; 001B-3: Markdown renderer; 001B-2D: documentation analyzer; 001C: unified project map composer; 001C-G: orchestration.
+export * from './traverse.js';
+export * from './contracts.js';
+export * from './facts.js';
+export * from './render.js';
+export * from './docs.js';
+export * from './compose.js';
+export * from './orchestrate.js';

package/dist/discovery/orchestrate.d.ts

@@ -0,0 +1,35 @@
+/**
+ * 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 { type AnalyzeDocumentationOptions } from './docs.js';
+import { type ExtractOptions } from './facts.js';
+import { type TraverseOptions } from './traverse.js';
+export interface DiscoverProjectMapOptions {
+    /** Passed to the single traversal. */
+    traversal?: TraverseOptions;
+    /** Passed to fact extraction. */
+    facts?: ExtractOptions;
+    /** Passed to the documentation analyzer. */
+    documentation?: AnalyzeDocumentationOptions;
+}
+/** Runs traversal → facts + documentation (same traversal object) → composer and returns the Project Map Markdown. */
+export declare function discoverProjectMap(projectRoot: string, options?: DiscoverProjectMapOptions): string;
+//# sourceMappingURL=orchestrate.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"orchestrate.d.ts","sourceRoot":"","sources":["../../src/discovery/orchestrate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAwB,KAAK,2BAA2B,EAAE,MAAM,WAAW,CAAC;AAEnF,OAAO,EAAuB,KAAK,cAAc,EAAE,MAAM,YAAY,CAAC;AACtE,OAAO,EAAmB,KAAK,eAAe,EAAE,MAAM,eAAe,CAAC;AAEtE,MAAM,WAAW,yBAAyB;IACxC,sCAAsC;IACtC,SAAS,CAAC,EAAE,eAAe,CAAC;IAC5B,iCAAiC;IACjC,KAAK,CAAC,EAAE,cAAc,CAAC;IACvB,4CAA4C;IAC5C,aAAa,CAAC,EAAE,2BAA2B,CAAC;CAC7C;AAED,sHAAsH;AACtH,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,GAAE,yBAA8B,GAAG,MAAM,CAKvG"}