@aexol/spectral 0.9.128 → 0.9.130

package/dist/agent/index.js

@@ -228,8 +228,8 @@ export function resolveSubagentTools(toolNames, cwd, ext, ctx) {
         const toolDef = richApi.getToolDefinition(name);
         if (toolDef) {
             const isolatedContext = name === RECALL_OBSERVATION_TOOL_NAME
-                ? { cwd, sessionManager: createSubagentSessionManagerSnapshot(ctx.sessionManager) }
-                : { cwd };
+                ? { cwd, sessionManager: createSubagentSessionManagerSnapshot(ctx.sessionManager), getSystemPrompt: ctx.getSystemPrompt }
+                : { cwd, getSystemPrompt: ctx.getSystemPrompt };
             const isolatedContextWithNoParent = isolatedContext;
             tools.push(wrapToolDefinition(toolDef, () => isolatedContextWithNoParent));
         }

package/dist/extensions/code-order/analyzer.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Code Order — directory walker, size aggregation and metrics.
+ *
+ * Iterative (stack-based) traversal — never recurses so deep trees cannot blow
+ * the call stack. Honors a hardcoded ignore list (node_modules, .git, dist…),
+ * a hard cap on scanned files, and a max depth.
+ *
+ * The walker builds the full folder tree in one pass, aggregating size,
+ * file/folder counts and max depth into each FolderNode as it unwinds.
+ */
+import type { AnalysisResult, FileNode, FolderNode, ProjectMetrics, TreeNode, Issue } from "./types.js";
+/** Returns true for media/binary extensions that should not be flagged as oversized. */
+declare function isBinaryExtension(ext: string): boolean;
+/**
+ * Walk the directory tree under `root` and return the full folder tree plus
+ * flat lists of every file/folder encountered (used for metrics + heuristics).
+ */
+export declare function walkTree(root: string): Promise<{
+    tree: FolderNode;
+    allFiles: FileNode[];
+    allFolders: string[];
+    maxDepth: number;
+    fileCount: number;
+}>;
+/**
+ * Compute project-wide metrics from the flat file list.
+ */
+export declare function computeMetrics(allFiles: FileNode[], allFolders: string[], maxDepth: number): ProjectMetrics;
+/** How many top items to keep in ranked lists. Exposed for tests. */
+export declare const TOP_N: 15;
+/** Exposed so heuristics.ts can use the same thresholds. */
+export declare const HEURISTIC_LIMITS: {
+    /** Stop scanning after this many files regardless of depth. */
+    readonly maxFiles: 50000;
+    /** Maximum directory depth the walker descends into. */
+    readonly maxDepth: 20;
+    /** A file larger than this (bytes) is flagged as oversized. */
+    readonly largeFileThreshold: 100000;
+    /** A directory deeper than this is flagged as deep nesting. */
+    readonly deepNestingThreshold: 8;
+    /** How many items to keep in "top N" lists. */
+    readonly topN: 15;
+};
+export { isBinaryExtension };
+/** Re-exported for the analyzer entry point. */
+export type { AnalysisResult, Issue, TreeNode, FolderNode, FileNode };
+//# sourceMappingURL=analyzer.d.ts.map

package/dist/extensions/code-order/analyzer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analyzer.d.ts","sourceRoot":"","sources":["../../../src/extensions/code-order/analyzer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAKH,OAAO,KAAK,EACX,cAAc,EAEd,QAAQ,EACR,UAAU,EACV,cAAc,EACd,QAAQ,EACR,KAAK,EACL,MAAM,YAAY,CAAC;AAmDpB,wFAAwF;AACxF,iBAAS,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAE/C;AAkDD;;;GAGG;AACH,wBAAsB,QAAQ,CAC7B,IAAI,EAAE,MAAM,GACV,OAAO,CAAC;IACV,IAAI,EAAE,UAAU,CAAC;IACjB,QAAQ,EAAE,QAAQ,EAAE,CAAC;IACrB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CAClB,CAAC,CAiKD;AAWD;;GAEG;AACH,wBAAgB,cAAc,CAC7B,QAAQ,EAAE,QAAQ,EAAE,EACpB,UAAU,EAAE,MAAM,EAAE,EACpB,QAAQ,EAAE,MAAM,GACd,cAAc,CAwChB;AAED,qEAAqE;AACrE,eAAO,MAAM,KAAK,IAAc,CAAC;AAEjC,4DAA4D;AAC5D,eAAO,MAAM,gBAAgB;IA3R5B,+DAA+D;;IAE/D,wDAAwD;;IAExD,+DAA+D;;IAE/D,+DAA+D;;IAE/D,+CAA+C;;CAmRV,CAAC;AACvC,OAAO,EAAE,iBAAiB,EAAE,CAAC;AAE7B,gDAAgD;AAChD,YAAY,EAAE,cAAc,EAAE,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAE,QAAQ,EAAE,CAAC"}

package/dist/extensions/code-order/analyzer.js

@@ -0,0 +1,315 @@
+/**
+ * Code Order — directory walker, size aggregation and metrics.
+ *
+ * Iterative (stack-based) traversal — never recurses so deep trees cannot blow
+ * the call stack. Honors a hardcoded ignore list (node_modules, .git, dist…),
+ * a hard cap on scanned files, and a max depth.
+ *
+ * The walker builds the full folder tree in one pass, aggregating size,
+ * file/folder counts and max depth into each FolderNode as it unwinds.
+ */
+import { stat } from "node:fs/promises";
+import { join, relative, sep, basename, extname } from "node:path";
+import { readdir } from "node:fs/promises";
+/** Directory names that are skipped outright (matched against the basename). */
+const IGNORED_DIRS = new Set([
+    "node_modules",
+    ".git",
+    "dist",
+    "dist-release",
+    "build",
+    ".next",
+    ".turbo",
+    ".cache",
+    ".deno",
+    "coverage",
+    ".nyc_output",
+    "vendor",
+    "__pycache__",
+    ".pytest_cache",
+    ".venv",
+    "venv",
+    "env",
+    "target",
+    "out",
+    "release",
+    "releases",
+    ".gradle",
+    ".idea",
+    ".vscode",
+    ".sst",
+    ".serverless",
+    ".terraform",
+    ".logs",
+    "logs",
+    ".svelte-kit",
+    ".parcel-cache",
+]);
+/** File basenames that are skipped outright. */
+const IGNORED_FILES = new Set([".DS_Store", "Thumbs.db"]);
+/** Binary/media extensions whose large size is expected and unactionable. */
+const BINARY_EXTENSIONS = new Set([
+    "png", "jpg", "jpeg", "gif", "webp", "bmp", "ico", "tiff", "svg",
+    "mp4", "webm", "mov", "avi", "mkv", "mp3", "wav", "flac", "ogg",
+    "pdf", "zip", "tar", "gz", "tgz", "bz2", "7z", "rar",
+    "woff", "woff2", "ttf", "otf", "eot",
+    "dylib", "so", "dll", "exe", "bin", "class", "jar",
+    "sqlite", "db", "lockb",
+    "pak", "dat", "dat1", "index",
+]);
+/** Returns true for media/binary extensions that should not be flagged as oversized. */
+function isBinaryExtension(ext) {
+    return BINARY_EXTENSIONS.has(ext);
+}
+/** Hard safety limits — no configuration exposed to the user. */
+const LIMITS = {
+    /** Stop scanning after this many files regardless of depth. */
+    maxFiles: 50_000,
+    /** Maximum directory depth the walker descends into. */
+    maxDepth: 20,
+    /** A file larger than this (bytes) is flagged as oversized. */
+    largeFileThreshold: 100_000,
+    /** A directory deeper than this is flagged as deep nesting. */
+    deepNestingThreshold: 8,
+    /** How many items to keep in "top N" lists. */
+    topN: 15,
+};
+function isIgnoredDir(name) {
+    return IGNORED_DIRS.has(name);
+}
+function isIgnoredFile(name) {
+    if (IGNORED_FILES.has(name))
+        return true;
+    // Skip lock files (package-lock.json, yarn.lock, Cargo.lock, …) — they are
+    // generated and would dominate the size metrics.
+    return /(?:^|\.)(?:lock)$/i.test(name) || name.endsWith(".lock");
+}
+function shouldIgnoreEntry(name, isDir) {
+    return isDir ? isIgnoredDir(name) : isIgnoredFile(name);
+}
+async function safeStat(p) {
+    try {
+        const s = await stat(p);
+        return { size: s.size, mtime: s.mtimeMs, isDir: s.isDirectory() };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Walk the directory tree under `root` and return the full folder tree plus
+ * flat lists of every file/folder encountered (used for metrics + heuristics).
+ */
+export async function walkTree(root) {
+    const allFiles = [];
+    const allFolders = [];
+    let fileCount = 0;
+    let maxDepth = 0;
+    // Stack of pending directories to process.
+    const stack = [{ dir: root, depth: 0 }];
+    // Map from directory path → built node metadata (children, depth).
+    // We process directories bottom-up: a folder is finalized after all of
+    // its descendants have been finalized.
+    const pending = new Map();
+    // Seed the root folder node.
+    const rootName = basename(root) || root;
+    pending.set(root, {
+        node: {
+            path: ".",
+            name: rootName,
+            isFile: false,
+            totalSize: 0,
+            fileCount: 0,
+            folderCount: 0,
+            maxDepth: 0,
+            children: [],
+        },
+        depth: 0,
+    });
+    allFolders.push(".");
+    while (stack.length > 0) {
+        const item = stack.pop();
+        const { dir, depth } = item;
+        if (depth > maxDepth)
+            maxDepth = depth;
+        if (depth >= LIMITS.maxDepth)
+            continue;
+        if (fileCount >= LIMITS.maxFiles)
+            break;
+        let entries;
+        try {
+            entries = await readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            continue; // permission error or vanished — skip silently
+        }
+        // Stable order: folders first, then files, alphabetical within.
+        const dirs = [];
+        const files = [];
+        for (const e of entries) {
+            if (shouldIgnoreEntry(e.name, e.isDirectory()))
+                continue;
+            if (e.isDirectory())
+                dirs.push(e.name);
+            else if (e.isFile())
+                files.push(e.name);
+        }
+        dirs.sort((a, b) => a.localeCompare(b));
+        files.sort((a, b) => a.localeCompare(b));
+        // Queue subdirectories for processing.
+        for (const d of dirs) {
+            const child = join(dir, d);
+            const rel = relative(root, child).split(sep).join("/");
+            const parentBuilt = pending.get(dir);
+            const childDepth = depth + 1;
+            pending.set(child, {
+                node: {
+                    path: rel,
+                    name: d,
+                    isFile: false,
+                    totalSize: 0,
+                    fileCount: 0,
+                    folderCount: 0,
+                    maxDepth: 0,
+                    children: [],
+                },
+                depth: childDepth,
+            });
+            allFolders.push(rel);
+            if (parentBuilt) {
+                // placeholder child; size updated when finalized
+                parentBuilt.node.children.push({
+                    path: rel,
+                    name: d,
+                    isFile: false,
+                    totalSize: 0,
+                    fileCount: 0,
+                    folderCount: 0,
+                    maxDepth: 0,
+                    children: [],
+                });
+            }
+            stack.push({ dir: child, depth: childDepth });
+        }
+        // Process files in this directory immediately.
+        const built = pending.get(dir);
+        if (!built)
+            continue;
+        for (const f of files) {
+            if (fileCount >= LIMITS.maxFiles)
+                break;
+            const fullPath = join(dir, f);
+            const rel = relative(root, fullPath).split(sep).join("/");
+            const info = await safeStat(fullPath);
+            if (!info || info.isDir)
+                continue;
+            fileCount++;
+            const node = {
+                path: rel,
+                name: f,
+                size: info.size,
+                extension: extname(f).slice(1).toLowerCase(),
+                isFile: true,
+                mtime: info.mtime,
+            };
+            allFiles.push(node);
+            built.node.children.push(node);
+            built.node.totalSize += info.size;
+            built.node.fileCount += 1;
+        }
+    }
+    // Finalize folders bottom-up: aggregate child totals into each parent.
+    // Sort by descending depth so children are processed before parents.
+    const foldersByDepth = Array.from(pending.entries()).sort((a, b) => b[1].depth - a[1].depth);
+    for (const [absPath, built] of foldersByDepth) {
+        // Recompute aggregates from finalized children.
+        let size = 0;
+        let fc = 0;
+        let foc = 0;
+        let md = built.depth;
+        for (const child of built.node.children) {
+            if (child.isFile) {
+                size += child.size;
+                fc += 1;
+            }
+            else {
+                size += child.totalSize;
+                fc += child.fileCount;
+                foc += 1 + child.folderCount;
+                if (child.maxDepth > md)
+                    md = child.maxDepth;
+            }
+        }
+        built.node.totalSize = size;
+        built.node.fileCount = fc;
+        built.node.folderCount = foc;
+        built.node.maxDepth = md;
+        // Propagate up into the parent's child placeholder (if any).
+        const parentPath = absPath === root ? null : join(absPath, "..");
+        if (parentPath && parentPath !== absPath) {
+            const parentBuilt = pending.get(parentPath);
+            if (parentBuilt) {
+                // Replace the placeholder child we pushed earlier.
+                const idx = parentBuilt.node.children.findIndex((c) => !c.isFile && c.path === built.node.path);
+                if (idx >= 0) {
+                    parentBuilt.node.children[idx] = built.node;
+                }
+            }
+        }
+    }
+    const tree = pending.get(root).node;
+    return { tree, allFiles, allFolders, maxDepth, fileCount };
+}
+function median(values) {
+    if (values.length === 0)
+        return 0;
+    const sorted = [...values].sort((a, b) => a - b);
+    const mid = Math.floor(sorted.length / 2);
+    return sorted.length % 2 === 0
+        ? Math.round((sorted[mid - 1] + sorted[mid]) / 2)
+        : sorted[mid];
+}
+/**
+ * Compute project-wide metrics from the flat file list.
+ */
+export function computeMetrics(allFiles, allFolders, maxDepth) {
+    const totalFiles = allFiles.length;
+    const totalSize = allFiles.reduce((s, f) => s + f.size, 0);
+    const avgFileSize = totalFiles > 0 ? Math.round(totalSize / totalFiles) : 0;
+    const medianFileSize = median(allFiles.map((f) => f.size));
+    const extMap = new Map();
+    for (const f of allFiles) {
+        const ext = f.extension || "(none)";
+        const entry = extMap.get(ext) ?? { extension: ext, count: 0, size: 0 };
+        entry.count += 1;
+        entry.size += f.size;
+        extMap.set(ext, entry);
+    }
+    const extensions = [...extMap.values()]
+        .sort((a, b) => b.size - a.size || b.count - a.count);
+    const topLargestFiles = [...allFiles]
+        .sort((a, b) => b.size - a.size)
+        .slice(0, LIMITS.topN);
+    const emptyFiles = allFiles.filter((f) => f.size === 0).map((f) => f.path);
+    // Empty folders: folders whose path never appears as a parent of any file.
+    // (We can't easily tell from the flat folder list, so we derive from the
+    // tree during heuristics instead.)
+    const emptyFolders = [];
+    return {
+        totalFiles,
+        totalFolders: allFolders.length,
+        totalSize,
+        maxDepth,
+        avgFileSize,
+        medianFileSize,
+        extensions,
+        topLargestFiles,
+        emptyFolders,
+        emptyFiles,
+    };
+}
+/** How many top items to keep in ranked lists. Exposed for tests. */
+export const TOP_N = LIMITS.topN;
+/** Exposed so heuristics.ts can use the same thresholds. */
+export const HEURISTIC_LIMITS = LIMITS;
+export { isBinaryExtension };

package/dist/extensions/code-order/heuristics.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Code Order — structural heuristics.
+ *
+ * Each heuristic scans the flat file/folder lists (and the tree) and emits
+ * {@link Issue} entries. Issues are the actionable findings the final report
+ * surfaces to the agent: oversized files, deep nesting, empty folders, etc.
+ *
+ * Thresholds live in `analyzer.ts` (HEURISTIC_LIMITS) and are intentionally
+ * not user-configurable — tree-like structure is always better.
+ */
+import type { FileNode, FolderNode, Issue, ProjectMetrics } from "./types.js";
+/** Detect source files exceeding the oversized threshold. Binary/media files are skipped. */
+export declare function findOversizedFiles(files: FileNode[]): Issue[];
+/**
+ * Detect folders whose depth exceeds the nesting threshold.
+ * `folderDepths` maps folder path → depth.
+ */
+export declare function findDeepNesting(folderDepths: Map<string, number>): Issue[];
+/** Detect folders that contain no files (directly or in any descendant). */
+export declare function findEmptyFolders(tree: FolderNode): Issue[];
+/** Detect zero-byte files. */
+export declare function findEmptyFiles(files: FileNode[]): Issue[];
+/**
+ * Detect folders that contain exactly one child (file or folder).
+ * Single-child folders are candidates for flattening into their parent.
+ */
+export declare function findSingleChildFolders(tree: FolderNode): Issue[];
+/**
+ * Detect sibling folders with duplicate names within the same parent.
+ * Highlights accidental parallel structure (e.g. two `utils/` folders).
+ */
+export declare function findDuplicateFolderNames(tree: FolderNode): Issue[];
+/** Map of folder path → depth, derived from the flat folder list. */
+export declare function computeFolderDepths(allFolders: string[]): Map<string, number>;
+/** Convenience: run every heuristic and return the combined, sorted issue list. */
+export declare function runAllHeuristics(tree: FolderNode, allFiles: FileNode[], allFolders: string[], metrics: ProjectMetrics): Issue[];
+//# sourceMappingURL=heuristics.d.ts.map

package/dist/extensions/code-order/heuristics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"heuristics.d.ts","sourceRoot":"","sources":["../../../src/extensions/code-order/heuristics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAE,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAU9E,6FAA6F;AAC7F,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,QAAQ,EAAE,GAAG,KAAK,EAAE,CAiB7D;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,KAAK,EAAE,CAa1E;AAED,4EAA4E;AAC5E,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,UAAU,GAAG,KAAK,EAAE,CAyB1D;AAED,8BAA8B;AAC9B,wBAAgB,cAAc,CAAC,KAAK,EAAE,QAAQ,EAAE,GAAG,KAAK,EAAE,CAWzD;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,UAAU,GAAG,KAAK,EAAE,CAmBhE;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,UAAU,GAAG,KAAK,EAAE,CA2BlE;AAED,qEAAqE;AACrE,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAM7E;AAED,mFAAmF;AACnF,wBAAgB,gBAAgB,CAC/B,IAAI,EAAE,UAAU,EAChB,QAAQ,EAAE,QAAQ,EAAE,EACpB,UAAU,EAAE,MAAM,EAAE,EACpB,OAAO,EAAE,cAAc,GACrB,KAAK,EAAE,CAoBT"}

package/dist/extensions/code-order/heuristics.js

@@ -0,0 +1,188 @@
+/**
+ * Code Order — structural heuristics.
+ *
+ * Each heuristic scans the flat file/folder lists (and the tree) and emits
+ * {@link Issue} entries. Issues are the actionable findings the final report
+ * surfaces to the agent: oversized files, deep nesting, empty folders, etc.
+ *
+ * Thresholds live in `analyzer.ts` (HEURISTIC_LIMITS) and are intentionally
+ * not user-configurable — tree-like structure is always better.
+ */
+import { dirname } from "node:path";
+import { HEURISTIC_LIMITS, isBinaryExtension } from "./analyzer.js";
+function formatBytes(n) {
+    if (n < 1024)
+        return `${n} B`;
+    if (n < 1024 * 1024)
+        return `${(n / 1024).toFixed(1)} KB`;
+    if (n < 1024 * 1024 * 1024)
+        return `${(n / (1024 * 1024)).toFixed(1)} MB`;
+    return `${(n / (1024 * 1024 * 1024)).toFixed(2)} GB`;
+}
+/** Detect source files exceeding the oversized threshold. Binary/media files are skipped. */
+export function findOversizedFiles(files) {
+    const threshold = HEURISTIC_LIMITS.largeFileThreshold;
+    return files
+        .filter((f) => f.size > threshold && !isBinaryExtension(f.extension))
+        .sort((a, b) => b.size - a.size)
+        .slice(0, HEURISTIC_LIMITS.topN)
+        .map((f) => {
+        const sev = f.size > threshold * 10 ? "critical" : "warning";
+        return {
+            type: "oversized_file",
+            severity: sev,
+            path: f.path,
+            message: `File is ${formatBytes(f.size)} (threshold ${formatBytes(threshold)})`,
+            suggestion: "Consider splitting into smaller modules or moving large generated content out of source.",
+        };
+    });
+}
+/**
+ * Detect folders whose depth exceeds the nesting threshold.
+ * `folderDepths` maps folder path → depth.
+ */
+export function findDeepNesting(folderDepths) {
+    const threshold = HEURISTIC_LIMITS.deepNestingThreshold;
+    return [...folderDepths.entries()]
+        .filter(([, d]) => d > threshold)
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, HEURISTIC_LIMITS.topN)
+        .map(([path, d]) => ({
+        type: "deep_nesting",
+        severity: "warning",
+        path,
+        message: `Directory at depth ${d} (threshold ${threshold})`,
+        suggestion: "Consider flattening the hierarchy — deep nesting hurts LLM navigability.",
+    }));
+}
+/** Detect folders that contain no files (directly or in any descendant). */
+export function findEmptyFolders(tree) {
+    const out = [];
+    const visit = (node) => {
+        let hasFile = false;
+        for (const child of node.children) {
+            if (child.isFile) {
+                hasFile = true;
+            }
+            else {
+                const sub = visit(child);
+                if (sub.hasFile)
+                    hasFile = true;
+            }
+        }
+        if (!hasFile && node.path !== ".") {
+            out.push({
+                type: "empty_folder",
+                severity: "info",
+                path: node.path,
+                message: "Folder contains no files (recursively)",
+                suggestion: "Safe to remove if not intentionally empty for conventions.",
+            });
+        }
+        return { hasFile };
+    };
+    visit(tree);
+    return out.slice(0, HEURISTIC_LIMITS.topN);
+}
+/** Detect zero-byte files. */
+export function findEmptyFiles(files) {
+    return files
+        .filter((f) => f.size === 0)
+        .slice(0, HEURISTIC_LIMITS.topN)
+        .map((f) => ({
+        type: "empty_file",
+        severity: "info",
+        path: f.path,
+        message: "File is empty (0 bytes)",
+        suggestion: "Remove if unused, or add a placeholder comment.",
+    }));
+}
+/**
+ * Detect folders that contain exactly one child (file or folder).
+ * Single-child folders are candidates for flattening into their parent.
+ */
+export function findSingleChildFolders(tree) {
+    const out = [];
+    const visit = (node) => {
+        if (node.path !== "." && node.children.length === 1) {
+            const only = node.children[0];
+            out.push({
+                type: "single_child_folder",
+                severity: "info",
+                path: node.path,
+                message: `Folder contains a single child: ${only.name}`,
+                suggestion: "Consider merging into the parent to reduce nesting.",
+            });
+        }
+        for (const child of node.children) {
+            if (!child.isFile)
+                visit(child);
+        }
+    };
+    visit(tree);
+    return out.slice(0, HEURISTIC_LIMITS.topN);
+}
+/**
+ * Detect sibling folders with duplicate names within the same parent.
+ * Highlights accidental parallel structure (e.g. two `utils/` folders).
+ */
+export function findDuplicateFolderNames(tree) {
+    const out = [];
+    const visit = (node) => {
+        const byName = new Map();
+        for (const child of node.children) {
+            if (child.isFile)
+                continue;
+            const arr = byName.get(child.name) ?? [];
+            arr.push(child);
+            byName.set(child.name, arr);
+        }
+        for (const [, arr] of byName) {
+            if (arr.length > 1) {
+                out.push({
+                    type: "duplicate_names",
+                    severity: "warning",
+                    path: node.path,
+                    message: `${arr.length} sibling folders share the name "${arr[0].name}"`,
+                    suggestion: "Consolidate duplicate sibling folders.",
+                });
+            }
+        }
+        for (const child of node.children) {
+            if (!child.isFile)
+                visit(child);
+        }
+    };
+    visit(tree);
+    return out.slice(0, HEURISTIC_LIMITS.topN);
+}
+/** Map of folder path → depth, derived from the flat folder list. */
+export function computeFolderDepths(allFolders) {
+    const depths = new Map();
+    for (const p of allFolders) {
+        depths.set(p, p === "." ? 0 : p.split("/").length);
+    }
+    return depths;
+}
+/** Convenience: run every heuristic and return the combined, sorted issue list. */
+export function runAllHeuristics(tree, allFiles, allFolders, metrics) {
+    const folderDepths = computeFolderDepths(allFolders);
+    const issues = [
+        ...findOversizedFiles(allFiles),
+        ...findDeepNesting(folderDepths),
+        ...findEmptyFolders(tree),
+        ...findEmptyFiles(allFiles),
+        ...findSingleChildFolders(tree),
+        ...findDuplicateFolderNames(tree),
+    ];
+    // Severity sort: critical > warning > info, then by path.
+    const order = { critical: 0, warning: 1, info: 2 };
+    issues.sort((a, b) => order[a.severity] - order[b.severity] || a.path.localeCompare(b.path));
+    // Patch emptyFolders into metrics (computed here, not in computeMetrics).
+    metrics.emptyFolders = issues
+        .filter((i) => i.type === "empty_folder")
+        .map((i) => i.path);
+    // Suppress unused-import lint for dirname (kept for future path math).
+    void dirname;
+    return issues;
+}

package/dist/extensions/code-order/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Code Order — native spectral extension.
+ *
+ * Registers a single tool, `code_order_report`, that scans the current
+ * project's directory tree and returns a Markdown cleanup report: oversized
+ * files, deep nesting, empty folders/files, duplicate sibling names and
+ * single-child folders. Language-agnostic, read-only, zero configuration.
+ *
+ * The report is input for the agent — it deduces what to split or flatten
+ * outside of this extension. Tree-like structure is enforced separately via
+ * the system prompt guidelines (see system-prompt.ts).
+ */
+import type { ExtensionAPI } from "../../sdk/coding-agent/index.js";
+export default function codeOrderExtension(ext: ExtensionAPI): Promise<void>;
+//# sourceMappingURL=index.d.ts.map

package/dist/extensions/code-order/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/extensions/code-order/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,KAAK,EAEX,YAAY,EAEZ,MAAM,iCAAiC,CAAC;AAMzC,wBAA8B,kBAAkB,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAgEjF"}