161. orc lays out its packages by Feature-Sliced Design, adapted to a command-line tool ​
Date: 2026-11-11
Status ​
Accepted. The eight first lint rules are in dependency-cruiser.config.ts, and the ninth, unlayered-file, and the tenth, unlayered-file-imports, land with the last move.
Context ​
orc is 16 packages, mostly command-line and library code. Its two largest, run with 122 source files and schema with 110, have no layering, and every folder in them is a flat list. The captain asked for the Feature-Sliced Design folder map, adapted to orc, before any backlog work. The scout measured every number below on e07e908, the head of main when the scout measured; main is now a376c40.
The captain's words ​
Feature-Sliced Design for orc: the folder map is approved as drawn, the twelve small packages stay one slice each with no layer folders, ui and tasks get purpose folders with no layers, entity slices import each other through index.ts kept free of cycles.
Quoted as firstmate recorded them in the brief of 2026-11-11.
Decision ​
The mapping of Feature-Sliced Design onto orc holds as follows.
- Layers.
runhas five layer folders,app,widgets,features,entitiesandshared, and 27 slices.schemahasfeatures,entitiesandshared, and 14 slices. A layer imports only the layers below it, in the order app, widgets, features, entities, shared. - Entry. A slice is entered only through its
index.ts. Between packages this already holds throughexportsin eachpackage.jsonand the preset ruleno-deep-imports. - No import between slices of one layer. No feature imports another feature, and no widget imports another widget.
- Entity slices may import each other through their
index.ts, andno-folder-cyclekeeps those imports free of cycles. Feature-Sliced Design forbids the import and adds one extra@xfile per pair; orc does not. sharedholds segments, not slices:shared/lib,shared/config,shared/process,shared/sandboxandshared/feeds. A segment may import another segment in either direction, only through that segment'sindex.ts.- Segments inside a slice.
schemaslices keep the folderscontract,sourcesandviews.runslices stay flat, since they hold 1 to 13 files each. - The
applayer keeps argument parsing and command dispatch inpackages/run/src/app/. The entry files stay wherepackage.json, the build script andknip.config.tsname them:packages/run/src/bin.tsandpackages/schema/src/index.ts. widgetshas one slice,widgets/beat, the one place that joins several features in a single pass.- The
pageslayer does not apply, since orc has no routed screens. Feature-Sliced Design is silent on tests, so the slice rules read onlypackages/*/src, and root tests reachrunby file path, sincerunpublishes no entry. - Layering between packages stays as it is.
schemasits underui, both sit under the panels, andclianddashboardsit on top. The five package rules already independency-cruiser.config.tshold this and stay. - A package under about 12 source files is one slice, with its
src/index.tsas its public file, and gets no layer folders. It gets purpose folders once it passes about 12 files, and layers only when it holds more than one user-facing purpose. Twelve packages stay one slice each:cli(11 files),session-quota(10),queues(9),resources(8),ledger(7),dashboard(6),alerts,dispatchandquota(5 each),herdr-app(5), andattentionandschedules(3 each). uigets five purpose folders and no layers, since the whole package is the shared drawing library and is one layer already.tasksgets two purpose folders,boardandsampler, and no layers.- Lint. dependency-cruiser carries every rule, in the existing
dependency-cruiser.config.ts. No new tool is added, and oxlint and knip do not change. The eight first rules areshared-imports-higher-layer,entities-imports-higher-layer,features-imports-higher-layer,widgets-imports-higher-layer,slice-imports-sibling,slice-internals,app-imports-slice-internalsandlayered-imports-unlayered. The ninth,unlayered-file, forbids a flat file inrunorschema, and the tenth,unlayered-file-imports, forbids a flat file from importing, and both land with the last move, since while flat files remain they report violations. - Order of work. Layers move from the bottom up:
sharedfirst, thenentities,features,widgetsandapp.layered-imports-unlayeredforbids a moved file from importing one not yet moved, which holds that order.
Consequences ​
- 260 files move under the layout. Git reads 259 as renames, 88 of them with no line changed.
- Imports inside
run,schema,ui,tasksand the tests are rewritten, about 1,100 of them. Of those about 725 go through a sliceindex.ts. Only paths intorunchange in the tests. No other package's imports change. - The entry points stay where they are:
packages/run/src/bin.ts, eachpackages/*/src/index.tsof the 14 packages that have one,packages/ui/src/bin-args.ts,packages/cli/src/bin.tsandpackages/session-quota/src/capture-bin.ts. - Docs that name a moved path change with it, about 118 lines.
Evidence ​
On main at a376c40, the eight first rules report 0 violations over 684 modules cruised, from the same run that reports 0 violations with the rules off. Each rule was checked by a probe file that it flagged, and the probe files were not committed.
What was considered and rejected ​
- Feature-Sliced Design's own ban on entity imports between slices, with an extra
@xfile per pair. It lost because it adds files and holds nothing thatno-folder-cycledoes not. - A
pageslayer. It lost because orc has no routed screens. - Layer folders in every package. It lost because a folder holding one or two files adds a path and nothing else.
- Segment folders inside
runslices. It lost because a slice of 1 to 13 files would hold one or two files in a segment folder. - steiger. It is not adopted. Its shape checks assume the layout as written, so the flat
runslices and the entity imports would need its rules switched off. This comes from its rule list; it was not run. - eslint-plugin-boundaries. It is not adopted. It needs ESLint, which this repository does not run, and its rules are the same from-path and to-path rules.
- oxlint's
no-restricted-imports. It is not adopted. It matches the text of an import, not the file the import resolves to.