@ankhorage/devtools 2.8.3 → 2.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -3,7 +3,7 @@
3
3
 
4
4
  # Ankhorage Devtools
5
5
 
6
- ![license: MIT](././paradox/badges/license.svg) ![npm: v2.8.3](././paradox/badges/npm.svg) ![runtime: bun](././paradox/badges/runtime.svg) ![typescript: strict](././paradox/badges/typescript.svg) ![eslint: checked](././paradox/badges/eslint.svg) ![prettier: checked](././paradox/badges/prettier.svg) ![build: checked](././paradox/badges/build.svg) ![tests: configured](././paradox/badges/tests.svg) ![paradox: warnings](././paradox/badges/docs.svg)
6
+ ![license: MIT](././paradox/badges/license.svg) ![npm: v2.9.0](././paradox/badges/npm.svg) ![runtime: bun](././paradox/badges/runtime.svg) ![typescript: strict](././paradox/badges/typescript.svg) ![eslint: checked](././paradox/badges/eslint.svg) ![prettier: checked](././paradox/badges/prettier.svg) ![build: checked](././paradox/badges/build.svg) ![tests: configured](././paradox/badges/tests.svg) ![paradox: warnings](././paradox/badges/docs.svg)
7
7
 
8
8
  Owns shared repository automation, managed development tooling, workflows, and agent standards for Ankhorage TypeScript projects.
9
9
 
@@ -29,15 +29,35 @@ async function renderAgentsFile(targetDirectory) {
29
29
  renderStandaloneRepositoryInstructions(),
30
30
  renderRequiredRepositoryInstructions(),
31
31
  renderDocumentationInstructions(),
32
+ renderGitHubTaskLifecycleInstructions(),
32
33
  renderPullRequestInstructions(),
33
34
  renderSkillScriptInstructions(),
34
35
  ].join('');
36
+ const nextAgentsBlock = await readNextAgentsBlockAsync(targetDirectory, manifest);
35
37
  return `# AGENTS.md
36
38
 
37
39
  <!-- This file is managed by @ankhorage/devtools. -->
38
-
39
- ${repositorySections}
40
- ${sections}`;
40
+ ${nextAgentsBlock}
41
+ ${repositorySections}${sections}`;
42
+ }
43
+ /*** Preserve Next.js's complete managed instruction block when Next owns the target. */
44
+ async function readNextAgentsBlockAsync(targetDirectory, manifest) {
45
+ if (!hasNextDependency(manifest))
46
+ return '';
47
+ try {
48
+ const contents = await readFile(resolve(targetDirectory, 'AGENTS.md'), 'utf8');
49
+ const match = NEXT_AGENTS_BLOCK_PATTERN.exec(contents);
50
+ return match === null ? '' : `${match[0]}\n`;
51
+ }
52
+ catch (error) {
53
+ if (isNodeError(error) && error.code === 'ENOENT')
54
+ return '';
55
+ throw error;
56
+ }
57
+ }
58
+ /*** Report whether the manifest directly declares Next.js. */
59
+ function hasNextDependency(manifest) {
60
+ return [manifest.dependencies, manifest.devDependencies].some((dependencies) => isRecord(dependencies) && typeof dependencies.next === 'string');
41
61
  }
42
62
  /*** Render the current-architecture policy shared by every managed repository. */
43
63
  function renderCurrentArchitectureInstructions() {
@@ -110,6 +130,30 @@ Paradox \`/*** ... */\` comments in \`src\` and leading \`@usage\` comments in r
110
130
  generated output. The managed release workflow runs \`bun run docs\` after the package version bump
111
131
  and commits the regenerated artifacts in the release commit.
112
132
 
133
+ `;
134
+ }
135
+ /*** Render the mandatory GitHub task isolation, delivery, and cleanup policy. */
136
+ function renderGitHubTaskLifecycleInstructions() {
137
+ return `## GitHub task lifecycle and workspace cleanup
138
+
139
+ - **Start.** Treat each issue implementation, PR implementation, review, and change request (CR)
140
+ as an independent task. Fetch the current remote default branch and read the applicable issue,
141
+ PR, HEAD, review feedback, and CI state. Use a fresh, uniquely named task checkout or worktree.
142
+ Concurrent tasks must have distinct writable checkout, temporary, build, and cache paths.
143
+ - **CRs.** Fetch and check out the current remote PR branch in the new workspace. Preserve PR
144
+ history and scope. Push corrections to the existing PR branch.
145
+ - **Delivery.** Run applicable checks. Commit and push all intended changes, then verify that
146
+ GitHub has the intended commit on the correct remote branch. Report the exact HEAD, checks, CI,
147
+ findings, and blockers. Report acceptance that was not run as unverified. Read-only reviews hand
148
+ off their findings without creating a commit. Merge requires explicit authorization.
149
+ - **Cleanup.** After handoff, resolve every candidate path and remove only task-owned directories
150
+ whose resolved paths are strictly under the resolved system path for \`/tmp\` (\`/private/tmp\` on
151
+ macOS). Refuse candidates that resolve outside that boundary, including through a symlink. Use
152
+ Git-aware removal for worktrees. Preserve workspaces outside the boundary, shared directories,
153
+ other tasks' directories, uncommitted changes, and unpushed commits. If blocked, persist
154
+ recoverable work first and document what must be retained. Report whether cleanup succeeded, was
155
+ skipped, or was blocked.
156
+
113
157
  `;
114
158
  }
115
159
  /*** Render canonical pull-request validation commands. */
@@ -171,3 +215,4 @@ function isRecord(value) {
171
215
  function readNonEmptyString(value) {
172
216
  return typeof value === 'string' && value.trim() !== '' ? value.trim() : null;
173
217
  }
218
+ const NEXT_AGENTS_BLOCK_PATTERN = /<!-- BEGIN:nextjs-agent-rules -->\r?\n[\s\S]*?<!-- END:nextjs-agent-rules -->/u;
@@ -54,13 +54,14 @@ export const defaultRestrictedImports = [
54
54
  export function createConfig(options) {
55
55
  const normalized = normalizeOptions(options);
56
56
  const profile = resolveEslintProfile(options);
57
- return defineConfig({ ignores: [...defaultIgnores, ...normalized.additionalIgnores] }, { ...js.configs.recommended, files: normalized.files }, ...createTypeCheckedConfigs(normalized), createBaseConfig(normalized), ...createProfileConfigs(profile, normalized.files), ...normalized.overrides, ...(normalized.includePrettier ? [prettierConfig] : []));
57
+ return defineConfig({ ignores: [...defaultIgnores, ...normalized.additionalIgnores] }, { ...js.configs.recommended, files: [...normalized.files, ...normalized.javascriptFiles] }, ...createTypeCheckedConfigs(normalized), createTypeScriptBaseConfig(normalized), ...createJavaScriptConfigs(normalized), ...createProfileConfigs(profile, [...normalized.files, ...normalized.javascriptFiles]), ...normalized.overrides, ...(normalized.includePrettier ? [prettierConfig] : []));
58
58
  }
59
59
  function normalizeOptions(options) {
60
60
  return {
61
61
  tsconfigRootDir: options.tsconfigRootDir,
62
62
  project: options.project,
63
63
  files: options.files,
64
+ javascriptFiles: options.javascriptFiles ?? [],
64
65
  allowDefaultProject: options.allowDefaultProject ?? [],
65
66
  additionalIgnores: options.additionalIgnores ?? [],
66
67
  restrictedImports: [...(options.restrictedImports ?? [])],
@@ -75,7 +76,7 @@ function createTypeCheckedConfigs(options) {
75
76
  ];
76
77
  return configs.map((config) => ({ ...config, files: options.files }));
77
78
  }
78
- function createBaseConfig(options) {
79
+ function createTypeScriptBaseConfig(options) {
79
80
  return {
80
81
  files: options.files,
81
82
  languageOptions: {
@@ -102,6 +103,28 @@ function createBaseConfig(options) {
102
103
  },
103
104
  };
104
105
  }
106
+ /*** Create the shared JavaScript policy without TypeScript project parsing. */
107
+ function createJavaScriptConfigs(options) {
108
+ if (options.javascriptFiles.length === 0)
109
+ return [];
110
+ return [
111
+ {
112
+ files: options.javascriptFiles,
113
+ plugins: {
114
+ import: importPlugin,
115
+ prettier: prettierPlugin,
116
+ security: securityPlugin,
117
+ 'simple-import-sort': simpleImportSort,
118
+ 'unused-imports': unusedImports,
119
+ },
120
+ rules: {
121
+ ...createImportRules(options),
122
+ ...createQualityRules(),
123
+ ...createSecurityRules(),
124
+ },
125
+ },
126
+ ];
127
+ }
105
128
  function createTypeScriptRules() {
106
129
  return {
107
130
  'no-unused-vars': 'off',
@@ -4,13 +4,15 @@ export declare const eslintManagedFiles: readonly [{
4
4
  readonly mode: "create-only";
5
5
  }, {
6
6
  readonly relativePath: "eslint.config.mjs";
7
- readonly contents: "import { createConfig } from '@ankhorage/devtools/eslint';\nimport localConfig from './eslint.local.config.mjs';\n\nconst localEntries = Array.isArray(localConfig) ? localConfig : [localConfig];\n\nexport default [\n ...createConfig({\n files: ['src/**/*.{ts,tsx}'],\n project: ['./tsconfig.json'],\n tsconfigRootDir: import.meta.dirname,\n }),\n ...localEntries,\n];\n";
7
+ readonly render: typeof renderManagedEslintConfigAsync;
8
8
  }, {
9
9
  readonly relativePath: "eslint.examples.config.mjs";
10
10
  readonly contents: "// This file is managed by @ankhorage/devtools.\nimport { existsSync } from 'node:fs';\n\nimport { createConfig } from '@ankhorage/devtools/eslint';\nimport localConfig from './eslint.local.config.mjs';\n\nconst exampleFiles = ['examples/**/*.{ts,tsx}'];\nconst localEntries = Array.isArray(localConfig) ? localConfig : [localConfig];\nconst rootProjects = ['./tsconfig.eslint.json', './tsconfig.json'].filter((project) =>\n existsSync(new URL(project, import.meta.url)),\n);\n\nexport default [\n ...createConfig({\n files: exampleFiles,\n project: [...rootProjects, './examples/**/tsconfig.json'],\n tsconfigRootDir: import.meta.dirname,\n }),\n ...localEntries,\n];\n";
11
11
  readonly isApplicable: typeof hasTypeScriptExamples;
12
12
  }];
13
13
  declare function renderInitialLocalConfig(targetDirectory: string): Promise<string>;
14
+ /*** Render canonical TypeScript and JavaScript scopes for the target's application profile. */
15
+ declare function renderManagedEslintConfigAsync(targetDirectory: string): Promise<string>;
14
16
  /*** Report whether the target repository owns TypeScript source examples at its root. */
15
17
  declare function hasTypeScriptExamples(targetDirectory: string): Promise<boolean>;
16
18
  export {};
@@ -1,20 +1,43 @@
1
1
  import { readdir, readFile } from 'node:fs/promises';
2
2
  import { resolve } from 'node:path';
3
3
  import { EXAMPLES_ESLINT_OWNERSHIP_MARKER } from '../../constants/eslint.js';
4
- const ESLINT_CONFIG = `import { createConfig } from '@ankhorage/devtools/eslint';
4
+ const DEFAULT_SOURCE_GLOBS = ['src/**/*.{ts,tsx}'];
5
+ const NEXT_JAVASCRIPT_SOURCE_GLOBS = [
6
+ 'src/**/*.{js,mjs,cjs}',
7
+ 'app/**/*.{js,mjs,cjs}',
8
+ 'components/**/*.{js,mjs,cjs}',
9
+ 'lib/**/*.{js,mjs,cjs}',
10
+ 'worker/**/*.{js,mjs,cjs}',
11
+ 'scripts/**/*.{js,mjs,cjs}',
12
+ 'tests/**/*.{js,mjs,cjs}',
13
+ ];
14
+ const NEXT_SOURCE_GLOBS = [
15
+ ...DEFAULT_SOURCE_GLOBS,
16
+ 'app/**/*.{ts,tsx}',
17
+ 'components/**/*.{ts,tsx}',
18
+ 'lib/**/*.{ts,tsx}',
19
+ 'worker/**/*.{ts,tsx}',
20
+ 'scripts/**/*.{ts,tsx}',
21
+ 'tests/**/*.{ts,tsx}',
22
+ ];
23
+ function renderEslintConfig(sourceGlobs, javascriptSourceGlobs = []) {
24
+ return `import { createConfig } from '@ankhorage/devtools/eslint';
5
25
  import localConfig from './eslint.local.config.mjs';
6
26
 
7
27
  const localEntries = Array.isArray(localConfig) ? localConfig : [localConfig];
8
28
 
9
29
  export default [
10
30
  ...createConfig({
11
- files: ['src/**/*.{ts,tsx}'],
31
+ files: ${JSON.stringify(sourceGlobs)},
32
+ javascriptFiles: ${JSON.stringify(javascriptSourceGlobs)},
12
33
  project: ['./tsconfig.json'],
13
34
  tsconfigRootDir: import.meta.dirname,
14
35
  }),
15
36
  ...localEntries,
16
37
  ];
17
38
  `;
39
+ }
40
+ const ESLINT_CONFIG = renderEslintConfig(DEFAULT_SOURCE_GLOBS);
18
41
  const EMPTY_LOCAL_CONFIG = `export default [];
19
42
  `;
20
43
  const IGNORED_EXAMPLE_DIRECTORY_NAMES = new Set([
@@ -56,7 +79,7 @@ export const eslintManagedFiles = [
56
79
  },
57
80
  {
58
81
  relativePath: 'eslint.config.mjs',
59
- contents: ESLINT_CONFIG,
82
+ render: renderManagedEslintConfigAsync,
60
83
  },
61
84
  {
62
85
  relativePath: 'eslint.examples.config.mjs',
@@ -76,9 +99,36 @@ async function renderInitialLocalConfig(targetDirectory) {
76
99
  throw error;
77
100
  }
78
101
  }
102
+ /*** Render canonical TypeScript and JavaScript scopes for the target's application profile. */
103
+ async function renderManagedEslintConfigAsync(targetDirectory) {
104
+ const manifest = await readPackageManifestAsync(targetDirectory);
105
+ return isNextApplication(manifest)
106
+ ? renderEslintConfig(NEXT_SOURCE_GLOBS, NEXT_JAVASCRIPT_SOURCE_GLOBS)
107
+ : renderEslintConfig(DEFAULT_SOURCE_GLOBS);
108
+ }
109
+ /*** Read the optional target manifest without changing the default source profile. */
110
+ async function readPackageManifestAsync(targetDirectory) {
111
+ try {
112
+ return JSON.parse(await readFile(resolve(targetDirectory, 'package.json'), 'utf8'));
113
+ }
114
+ catch (error) {
115
+ if (isNodeError(error) && error.code === 'ENOENT')
116
+ return undefined;
117
+ throw error;
118
+ }
119
+ }
120
+ /*** Report whether a manifest directly declares Next.js. */
121
+ function isNextApplication(manifest) {
122
+ if (!isRecord(manifest))
123
+ return false;
124
+ return [manifest.dependencies, manifest.devDependencies].some((dependencies) => isRecord(dependencies) && typeof dependencies.next === 'string');
125
+ }
79
126
  function isNodeError(error) {
80
127
  return error instanceof Error && 'code' in error;
81
128
  }
129
+ function isRecord(value) {
130
+ return typeof value === 'object' && value !== null && !Array.isArray(value);
131
+ }
82
132
  /*** Report whether the target repository owns TypeScript source examples at its root. */
83
133
  async function hasTypeScriptExamples(targetDirectory) {
84
134
  await assertExamplesConfigOwnershipAsync(targetDirectory);
@@ -10,6 +10,8 @@ export interface DevtoolsConfigOptions {
10
10
  readonly tsconfigRootDir: string;
11
11
  readonly project: string[];
12
12
  readonly files: string[];
13
+ /** JavaScript files that use the shared non-type-aware policy. */
14
+ readonly javascriptFiles?: string[];
13
15
  readonly profile?: DevtoolsEslintProfile;
14
16
  readonly packageJsonPath?: string;
15
17
  readonly allowDefaultProject?: string[];
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ankhorage/devtools",
3
- "version": "2.8.3",
3
+ "version": "2.9.0",
4
4
  "description": "Shared tooling, repository automation, and agent standards for Ankhorage TypeScript projects",
5
5
  "license": "MIT",
6
6
  "homepage": "https://github.com/ankhorage/devtools#readme",