diff --git a/README.md b/README.md index b36ac49..6e60fd7 100644 --- a/README.md +++ b/README.md @@ -24,10 +24,10 @@ running package installs. ## Workflow Skills DevNexus TypeScript ships baseline workflow skills for TypeScript diagnosis, -bounded refactoring, test hygiene, API boundary review, and dry-run codemod -planning. The plugin config declares them as `projected_skill` capabilities, and -the package also exports DevNexus skill definitions for projects that -materialize package-owned skills: +bounded refactoring, project topology, test hygiene, API boundary review, and +dry-run codemod planning. The plugin config declares them as `projected_skill` +capabilities, and the package also exports DevNexus skill definitions for +projects that materialize package-owned skills: ```ts import { diff --git a/skills/typescript-project-topology/REFERENCES.md b/skills/typescript-project-topology/REFERENCES.md new file mode 100644 index 0000000..bba5010 --- /dev/null +++ b/skills/typescript-project-topology/REFERENCES.md @@ -0,0 +1,8 @@ +# References + +- TypeScript `rootDir`: https://www.typescriptlang.org/tsconfig/rootDir.html +- TypeScript `outDir`: https://www.typescriptlang.org/tsconfig/outDir.html +- TypeScript `include`: https://www.typescriptlang.org/tsconfig/include.html +- Vitest test `include`: https://main.vitest.dev/config/include +- Vitest coverage config: https://vitest.dev/config/coverage.html +- npm `package.json` `files`: https://docs.npmjs.com/cli/v7/configuring-npm/package-json#files diff --git a/skills/typescript-project-topology/SKILL.md b/skills/typescript-project-topology/SKILL.md new file mode 100644 index 0000000..373288b --- /dev/null +++ b/skills/typescript-project-topology/SKILL.md @@ -0,0 +1,31 @@ +--- +name: typescript-project-topology +description: TypeScript project topology workflow for separating source, tests, build output, package files, and domain folders without changing behavior. Use when Codex must audit, design, or adjust TypeScript repository layout, especially src/test structure, package publish boundaries, or module grouping. +--- + +# TypeScript Project Topology + +Use this skill when a TypeScript or JavaScript project layout is being audited, +designed, or changed. + +1. Classify the project first: library, CLI, app, monorepo package, or test-only + fixture. Let package scripts, `exports`, `main`, `types`, and `files` define + the published surface. +2. Keep buildable implementation under a clear compiler root such as `src`, and + keep generated output under an ignored output directory such as `dist`. +3. For published packages and CLIs, prefer a central `test` tree that mirrors + source domains. This keeps test files out of emitted declarations, package + exports, and npm publish artifacts. +4. Colocated `*.test.ts` files are acceptable for small apps or local-only + packages when `tsconfig`, bundler, coverage, and package publish config all + exclude them reliably. +5. Avoid a flat source root once the package has durable domains. Group modules + by ownership, for example `cli`, `git`, `project`, `providers`, `automation`, + `publication`, `mcp`, and `shared`. +6. Mirror source domains in tests when using a central `test` tree. Prefer + `test//...` over one flat test directory for large packages. +7. Move topology in bounded mechanical steps. Preserve public imports and package + entrypoints, update internal imports, then run focused tests before full + package checks. +8. Do not move files solely for cosmetic symmetry. Use topology changes to + improve ownership, packaging safety, import locality, or test discoverability. diff --git a/skills/typescript-project-topology/dev-nexus.skill.json b/skills/typescript-project-topology/dev-nexus.skill.json new file mode 100644 index 0000000..476c669 --- /dev/null +++ b/skills/typescript-project-topology/dev-nexus.skill.json @@ -0,0 +1,14 @@ +{ + "id": "typescript-project-topology", + "name": "typescript-project-topology", + "description": "TypeScript project topology workflow for separating source, tests, build output, package files, and domain folders without changing behavior. Use when Codex must audit, design, or adjust TypeScript repository layout, especially src/test structure, package publish boundaries, or module grouping.", + "version": "0.1.0", + "license": "Apache-2.0", + "source": { + "type": "local", + "uri": "@evref-bl/dev-nexus-typescript/skills/typescript-project-topology" + }, + "supportedAgents": ["codex", "claude"], + "materialization": "copy", + "sourceControl": "support" +} diff --git a/src/devNexusTypeScriptPlugin.test.ts b/src/devNexusTypeScriptPlugin.test.ts index 272a9c5..b17d9f8 100644 --- a/src/devNexusTypeScriptPlugin.test.ts +++ b/src/devNexusTypeScriptPlugin.test.ts @@ -111,6 +111,7 @@ describe("DevNexus TypeScript plugin", () => { "node-modules", "skill-typescript-diagnose", "skill-typescript-refactor", + "skill-typescript-project-topology", "skill-typescript-test-hygiene", "skill-typescript-api-boundaries", "skill-typescript-codemod-planning", @@ -192,6 +193,13 @@ describe("DevNexus TypeScript plugin", () => { skillId: "typescript-refactor", targetAgents: ["codex", "claude"], }, + { + kind: "projected_skill", + id: "skill-typescript-project-topology", + description: "Project the TypeScript project directory topology workflow skill.", + skillId: "typescript-project-topology", + targetAgents: ["codex", "claude"], + }, { kind: "projected_skill", id: "skill-typescript-test-hygiene", @@ -227,6 +235,7 @@ describe("DevNexus TypeScript plugin", () => { ).toEqual([ "typescript-diagnose", "typescript-refactor", + "typescript-project-topology", "typescript-test-hygiene", "typescript-api-boundaries", "typescript-codemod-planning", @@ -377,7 +386,7 @@ describe("DevNexus TypeScript plugin", () => { pluginId: "dev-nexus-typescript", pluginName: "DevNexus TypeScript", version: devNexusTypeScriptPluginVersion, - capabilityCount: 11, + capabilityCount: 12, }, ]); expect(projected[0]!.capabilities.map((capability) => capability.kind)).toEqual([ @@ -387,6 +396,7 @@ describe("DevNexus TypeScript plugin", () => { "projected_skill", "projected_skill", "projected_skill", + "projected_skill", "mcp_server", "mcp_server", "mcp_server", @@ -405,6 +415,7 @@ describe("DevNexus TypeScript plugin", () => { "node-modules", "skill-typescript-diagnose", "skill-typescript-refactor", + "skill-typescript-project-topology", "skill-typescript-test-hygiene", "skill-typescript-api-boundaries", "skill-typescript-codemod-planning", diff --git a/src/typeScriptWorkflowSkills.test.ts b/src/typeScriptWorkflowSkills.test.ts index 3bcaeaf..8077b0e 100644 --- a/src/typeScriptWorkflowSkills.test.ts +++ b/src/typeScriptWorkflowSkills.test.ts @@ -9,6 +9,7 @@ describe("DevNexus TypeScript workflow skills", () => { expect(devNexusTypeScriptWorkflowSkillIds).toEqual([ "typescript-diagnose", "typescript-refactor", + "typescript-project-topology", "typescript-test-hygiene", "typescript-api-boundaries", "typescript-codemod-planning", @@ -19,6 +20,7 @@ describe("DevNexus TypeScript workflow skills", () => { expect(definitions.map((definition) => definition.manifest.id)).toEqual([ "typescript-diagnose", "typescript-refactor", + "typescript-project-topology", "typescript-test-hygiene", "typescript-api-boundaries", "typescript-codemod-planning", @@ -47,5 +49,15 @@ describe("DevNexus TypeScript workflow skills", () => { `"id": "${definition.manifest.id}"`, ); } + expect( + definitions.find( + (definition) => definition.manifest.id === "typescript-project-topology", + )!.files["SKILL.md"], + ).toContain("prefer a central `test` tree that mirrors"); + expect( + definitions.find( + (definition) => definition.manifest.id === "typescript-project-topology", + )!.files["REFERENCES.md"], + ).toContain("https://www.typescriptlang.org/tsconfig/rootDir.html"); }); }); diff --git a/src/typeScriptWorkflowSkills.ts b/src/typeScriptWorkflowSkills.ts index 6f6bc14..6d4d528 100644 --- a/src/typeScriptWorkflowSkills.ts +++ b/src/typeScriptWorkflowSkills.ts @@ -10,6 +10,7 @@ import type { export const devNexusTypeScriptWorkflowSkillIds = [ "typescript-diagnose", "typescript-refactor", + "typescript-project-topology", "typescript-test-hygiene", "typescript-api-boundaries", "typescript-codemod-planning", @@ -26,6 +27,8 @@ const projectedSkillDescriptions: Record< "Project the TypeScript compiler/runtime diagnosis workflow skill.", "typescript-refactor": "Project the bounded TypeScript refactoring workflow skill.", + "typescript-project-topology": + "Project the TypeScript project directory topology workflow skill.", "typescript-test-hygiene": "Project the TypeScript test hygiene workflow skill.", "typescript-api-boundaries": "Project the TypeScript API boundary review workflow skill.",