@@ -0,0 +1,26 @@
+# Implementation Log: `barrel` Command
+
+## 2026-07-10
+
+- Started implementation from `plan.md`.
+- Confirmed the command should be specifier-aware and should not reuse
+  `listIncomingDeps(...)` directly because that loses default/namespace import
+  details.
+- Added `src/commands/barrel.ts`, CLI wiring, and public API export.
+- Build issue: `pnpm build` tried to recreate `node_modules`; sandboxed network
+  failed with npm registry DNS errors. Reran with network approval and restored
+  dependencies.
+- TypeScript bug fixed: a local `PositionedNode` helper initially used an
+  interface extending Babel's `Node` union; changed it to an intersection type.
+- Added API tests for named imports, default imports, namespace imports,
+  type-only imports, re-export sources, skipped dynamic/side-effect imports,
+  collision rejection, and idempotent existing-index merges.
+- Added compiled CLI fixtures for apply, dry-run JSON, include/ignore,
+  idempotence, warnings, name collisions, and sibling `index.*` conflicts.
+- Added README documentation and a changeset for the new command.
+- Lint issue fixed: removed an unused helper after `oxlint` reported it.
+- Verification:
+  - `CI=true pnpm test:run` passed.
+  - `CI=true pnpm test:dist` passed.
+  - `CI=true pnpm build` passed.
+  - `CI=true pnpm lint` passed with no warnings after cleanup.
@@ -0,0 +1,256 @@
+# Plan: `barrel` Command
+
+## Goal
+
+Add `dosido barrel <directory>` as a mutating command that:
+
+- finds incoming static references from outside a directory to files inside it,
+- rewrites supported references to point at the directory itself,
+- creates or updates `<directory>/index.ts`,
+- exports only the names required by those rewritten references,
+- honors `--root`, `--dry-run`, `--json`, `--include`, and `--ignore`.
+
+## Accepted Semantics
+
+- Rewrite only references from outside the target directory. Leave internal
+  references alone.
+- Use `<directory>/index.ts` as the barrel file.
+- If a sibling barrel file already exists, such as `index.tsx`, `index.js`,
+  `index.mts`, or `index.mjs`, fail instead of reusing it.
+- If `index.ts` already exists, merge into it idempotently. Do not overwrite it.
+- Export only symbols needed by incoming references.
+- Rewrite default imports to named imports using the local default import name.
+- For namespace imports, generate a namespace value in the barrel:
+
+```ts
+import * as util from './util';
+export {util};
+```
+
+  Then rewrite the importer to `import {util} from './shared';`.
+- Skip string-literal dynamic imports with a warning.
+- Skip side-effect imports with a warning.
+- Do not support CommonJS `require(...)`.
+- Fail on public-name collisions rather than inventing aliases.
+- Generated paths from the barrel should prefer directory-index paths. For a
+  target like `src/shared/sub/index.ts`, render `./sub`, not `./sub/index`.
+
+## Phase 1: Fixtures And API Contract
+
+Add fixtures first so the behavior is locked before implementation details get
+too deep.
+
+1. Add `test/fixtures/barrel/named-imports-apply`.
+   - External imports reference two files inside a directory.
+   - Expected tree includes a new `index.ts`.
+   - External imports point at the directory.
+2. Add `test/fixtures/barrel/default-import`.
+   - Covers `import Button from './components/Button'`.
+   - Expected import is `import {Button} from './components';`.
+   - Expected barrel line is `export {default as Button} from './Button';`.
+3. Add `test/fixtures/barrel/mixed-default-and-named`.
+   - Covers one import declaration containing default and named specifiers.
+4. Add `test/fixtures/barrel/type-only`.
+   - Covers `import type`.
+   - Expected barrel uses `export type`.
+5. Add `test/fixtures/barrel/namespace-import`.
+   - Covers namespace import rewriting and generated namespace import/export in
+     the barrel.
+6. Add `test/fixtures/barrel/re-export-source`.
+   - Covers `export {x} from './shared/x'`.
+7. Add `test/fixtures/barrel/existing-index-idempotent`.
+   - Existing `index.ts` gets missing generated lines appended.
+   - A second run is a no-op or produces stable no-op output.
+8. Add negative fixtures:
+   - `name-collision`
+   - `dynamic-import-warning`
+   - `side-effect-import-warning`
+   - `sibling-index-conflict`
+   - `missing-directory`
+9. Add a dry-run JSON fixture.
+   - Assert planned changes and unchanged input tree.
+10. Add `include-ignore` coverage.
+
+Expected command shape:
+
+```bash
+dosido barrel <directory> [--include <glob>] [--ignore <glob>] [--json]
+```
+
+Expected public API shape:
+
+```ts
+makeBarrel({directory}, options)
+```
+
+## Phase 2: Command Skeleton
+
+Add the command entry points without the full rewrite logic yet.
+
+1. Create `src/commands/barrel.ts`.
+2. Define result and option types:
+   - `MakeBarrelArgs`
+   - `MakeBarrelOptions`
+   - `BarrelExport`
+   - `MakeBarrelResult`
+3. Add `makeBarrel(...)`.
+4. Validate:
+   - project root
+   - target directory exists and is a directory
+   - sibling `index.*` conflicts
+5. Return `CommandResult`-style fields:
+   - `changes`
+   - `messages`
+   - optional `warnings`
+6. Wire the CLI in `src/cli.ts`.
+   - Parse repeated `--include`.
+   - Parse repeated `--ignore`.
+   - Support `--json` via global parser.
+7. Export the API from `src/index.ts`.
+8. Update CLI help text.
+
+## Phase 3: Usage Collection
+
+Build a command-local AST collector that keeps source ranges and enough
+specifier detail to render replacements.
+
+1. Scan source files with `findSourceFiles(projectRoot, include, ignore)`.
+2. Skip files inside the target directory.
+3. Parse with `parseModule(...)`.
+4. For each supported declaration, resolve its source with
+   `resolveImportPath(...)`.
+5. Keep records only when the resolved target is inside the target directory.
+6. Record warnings and continue on parse errors.
+7. Collect these usage kinds:
+   - named import specifier
+   - default import specifier
+   - namespace import specifier
+   - named export-from specifier
+   - export namespace specifier, if Babel syntax support is already available
+   - dynamic import as skipped warning
+   - side-effect import as skipped warning
+8. Preserve:
+   - source file path
+   - resolved target file path
+   - declaration range
+   - source literal range
+   - import/export kind
+   - type-only status
+   - imported name, exported name, and local name as applicable
+
+Do not use `listIncomingDeps(...)` directly for this phase; it loses the
+specifier-level detail required for default and namespace rewrites.
+
+## Phase 4: Barrel Export Planner
+
+Transform usage records into deterministic barrel additions.
+
+1. Render barrel-relative source paths with a helper.
+   - Use `getRelativeImportPath(indexFile, targetFile)`.
+   - If the target file is an index module, strip trailing `/index`.
+2. Generate needed additions:
+   - Named value: `export {name} from './file';`
+   - Named type: `export type {Name} from './file';`
+   - Default: `export {default as LocalName} from './file';`
+   - Namespace: `import * as LocalName from './file';` plus `export {LocalName};`
+3. Track public barrel names.
+   - Named import public name is the imported/exported name.
+   - Default import public name is the local default name.
+   - Namespace import public name is the local namespace name.
+4. Detect collisions.
+   - Same public name from same target and same export form is okay.
+   - Same public name from different targets is an error.
+   - Same public name already exported by existing `index.ts` from another
+     target is an error.
+5. Sort additions for stable output.
+   - Value exports before type exports is fine, as long as it is deterministic.
+   - Keep namespace import/export pairs adjacent or otherwise predictable.
+
+## Phase 5: Import And Export Rewrites
+
+Apply source edits to each outside file.
+
+1. Compute the directory import specifier for each importer:
+
+```ts
+getRelativeImportPath(importerFile, targetDirectory)
+```
+
+2. For named-only import declarations:
+   - Preserve specifiers and aliases.
+   - Replace only the source literal.
+3. For default imports:
+   - Convert the default specifier to a named specifier using the local name.
+   - Preserve existing named specifiers and aliases.
+   - Preserve `import type` where valid.
+4. For mixed default plus named imports:
+   - Render one named import from the directory.
+5. For namespace imports:
+   - Rewrite `import * as util from './shared/util'` to
+     `import {util} from './shared';`.
+6. For named export-from declarations:
+   - Replace the source literal.
+7. For skipped dynamic and side-effect imports:
+   - Do not rewrite.
+   - Emit warnings that include the project-relative file path and original
+     source value.
+8. Use `applySourceEdits(...)` with ranges sorted through the existing helper.
+9. Do not write any files until every change has been planned successfully.
+
+## Phase 6: Existing `index.ts` Merge
+
+Make the barrel file update idempotent.
+
+1. If `index.ts` does not exist, create it with generated additions.
+2. If `index.ts` exists:
+   - Parse existing exports and namespace import/export pairs.
+   - Preserve all existing content.
+   - Append only missing generated additions.
+   - Ensure a trailing newline.
+3. Treat existing exports as part of collision detection.
+4. If parsing the existing index fails, fail the command before any writes.
+
+The first implementation can use generated line matching for duplicate
+detection, but it should still parse enough existing exports to detect public
+name conflicts.
+
+## Phase 7: CLI, Docs, And Public API
+
+1. Update `src/cli.ts` usage text.
+2. Add command branch for `barrel`.
+3. Update alias map only if a short alias is wanted.
+   - No alias is required for the first version.
+4. Update `src/index.ts` exports.
+5. Update `README.md`:
+   - command usage
+   - behavior notes for default and namespace imports
+   - skipped dynamic and side-effect imports
+6. Add a changeset if this repo expects one for user-facing command additions.
+
+## Phase 8: Verification
+
+Run focused tests first, then package-level checks.
+
+1. `pnpm test:run`
+2. `pnpm build`
+3. `pnpm test:dist`
+4. `pnpm lint`
+
+For fixtures that include `tsconfig.json`, use the existing `typecheck(project)`
+helper in the compiled CLI tests where practical.
+
+## Implementation Order
+
+1. Add the smallest API-level test for named imports.
+2. Implement enough `barrel.ts` to pass named imports.
+3. Add default import coverage and implement declaration rewriting.
+4. Add type-only and re-export coverage.
+5. Add namespace coverage.
+6. Add existing-index merge and idempotence.
+7. Add skipped dynamic and side-effect warning coverage.
+8. Add collision and sibling-index negative coverage.
+9. Wire compiled CLI fixtures.
+10. Update README and public exports.
+
+This order keeps the core path working early while delaying the high-risk
+collision and merge details until the shape of generated output is stable.