@ankhorage/devtools 2.2.2 → 2.3.6
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 +1 -1
- package/dist/cli/bin/repository.d.ts +2 -0
- package/dist/cli/bin/repository.js +17 -0
- package/dist/features/apm-release-validation/adapters/outbound/inspectPackedApmReleaseCandidateAsync.js +1 -1
- package/dist/tools/package/index.js +22 -3
- package/dist/tools/package/resolvePackageCapabilitiesAsync.d.ts +3 -0
- package/dist/tools/package/resolvePackageCapabilitiesAsync.js +59 -0
- package/dist/tools/prettier/formatYamlAsync.d.ts +2 -0
- package/dist/tools/prettier/formatYamlAsync.js +11 -0
- package/dist/tools/workflows/files/release.yml +40 -0
- package/dist/tools/workflows/renderWorkflowAsync.js +2 -1
- package/package.json +7 -6
package/README.md
CHANGED
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
|
|
4
4
|
# @ankhorage/devtools
|
|
5
5
|
|
|
6
|
-
         
|
|
7
7
|
|
|
8
8
|
Shared tooling, repository automation, and agent standards for Ankhorage TypeScript projects
|
|
9
9
|
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
import { findDevtoolsCommandByPath } from '../commands.js';
|
|
3
|
+
import { runRepositoryCommand } from '../runRepositoryCommand.js';
|
|
4
|
+
const [scope, operation, ...argv] = process.argv.slice(2);
|
|
5
|
+
const command = findDevtoolsCommandByPath([scope, operation]);
|
|
6
|
+
if (command?.kind !== 'repository') {
|
|
7
|
+
console.error('Usage: ankhorage-repository <scope> <sync|status> [directory] [--dry-run]');
|
|
8
|
+
process.exitCode = 1;
|
|
9
|
+
}
|
|
10
|
+
else {
|
|
11
|
+
const result = await runRepositoryCommand(command, argv, {
|
|
12
|
+
cwd: process.cwd(),
|
|
13
|
+
writeStdout: (text) => process.stdout.write(text),
|
|
14
|
+
writeStderr: (text) => process.stderr.write(text),
|
|
15
|
+
});
|
|
16
|
+
process.exitCode = result.exitCode;
|
|
17
|
+
}
|
|
@@ -17,8 +17,8 @@ export async function inspectPackedApmReleaseCandidateAsync(targetDirectory, opt
|
|
|
17
17
|
const temporaryRoot = await mkdtemp(resolve(tmpdir(), 'ankh-apm-release-'));
|
|
18
18
|
try {
|
|
19
19
|
const archive = resolve(temporaryRoot, 'candidate.tgz');
|
|
20
|
-
const packageRoot = resolve(temporaryRoot, 'package');
|
|
21
20
|
await packCandidateAsync(root, temporaryRoot, archive);
|
|
21
|
+
const packageRoot = await realpath(resolve(temporaryRoot, 'package'));
|
|
22
22
|
const candidate = await readPackedCandidateAsync(packageRoot, archive);
|
|
23
23
|
const result = await validatePackedCandidateAsync(candidate, packageRoot, root, options);
|
|
24
24
|
if (!result.valid || options.artifactPath === undefined)
|
|
@@ -22,6 +22,7 @@ import { readFile, writeFile } from 'node:fs/promises';
|
|
|
22
22
|
import { resolve } from 'node:path';
|
|
23
23
|
import { REPOSITORY_RULE_METADATA } from '@ankhorage/rules-repository';
|
|
24
24
|
import { applyBunRuntimePolicy } from '../../policy/applyBunRuntimePolicy.js';
|
|
25
|
+
import { resolvePackageCapabilitiesAsync } from './resolvePackageCapabilitiesAsync.js';
|
|
25
26
|
const PACKAGE_PATH = 'package.json';
|
|
26
27
|
const DEVTOOLS_PACKAGE_NAME = '@ankhorage/devtools';
|
|
27
28
|
const BUN_TYPES_PACKAGE_NAME = '@types/bun';
|
|
@@ -57,7 +58,7 @@ export async function inspectPackageManifest(targetDirectory, devtoolsVersion) {
|
|
|
57
58
|
}
|
|
58
59
|
return {
|
|
59
60
|
relativePath: PACKAGE_PATH,
|
|
60
|
-
state:
|
|
61
|
+
state: (await isManagedPackageContractCurrentAsync(snapshot.manifest, devtoolsVersion, snapshot.changesetsConfigExists, targetDirectory))
|
|
61
62
|
? 'current'
|
|
62
63
|
: 'outdated',
|
|
63
64
|
};
|
|
@@ -66,7 +67,7 @@ export async function inspectPackageManifest(targetDirectory, devtoolsVersion) {
|
|
|
66
67
|
export async function syncPackageManifest(targetDirectory, devtoolsVersion, options) {
|
|
67
68
|
const snapshot = await readPackageManifest(targetDirectory);
|
|
68
69
|
if (snapshot.exists &&
|
|
69
|
-
|
|
70
|
+
(await isManagedPackageContractCurrentAsync(snapshot.manifest, devtoolsVersion, snapshot.changesetsConfigExists, targetDirectory))) {
|
|
70
71
|
return { relativePath: PACKAGE_PATH, action: 'unchanged' };
|
|
71
72
|
}
|
|
72
73
|
if (options.dryRun) {
|
|
@@ -75,7 +76,11 @@ export async function syncPackageManifest(targetDirectory, devtoolsVersion, opti
|
|
|
75
76
|
action: snapshot.exists ? 'would-update' : 'would-create',
|
|
76
77
|
};
|
|
77
78
|
}
|
|
78
|
-
|
|
79
|
+
let updatedManifest = applyManagedPackageContract(snapshot.manifest, devtoolsVersion, snapshot.changesetsConfigExists);
|
|
80
|
+
const capabilities = await resolvePackageCapabilitiesAsync(targetDirectory, snapshot.manifest);
|
|
81
|
+
if (capabilities !== undefined) {
|
|
82
|
+
updatedManifest = applyManagedPackageCapabilities(updatedManifest, capabilities);
|
|
83
|
+
}
|
|
79
84
|
await writeFile(resolve(targetDirectory, PACKAGE_PATH), serializePackageManifest(updatedManifest), 'utf8');
|
|
80
85
|
return {
|
|
81
86
|
relativePath: PACKAGE_PATH,
|
|
@@ -106,6 +111,11 @@ export function applyManagedPackageContract(manifest, devtoolsVersion, changeset
|
|
|
106
111
|
devDependencies,
|
|
107
112
|
});
|
|
108
113
|
}
|
|
114
|
+
/*** Apply a canonical capability catalog without replacing authored Ankh metadata. */
|
|
115
|
+
function applyManagedPackageCapabilities(manifest, capabilities) {
|
|
116
|
+
const ankh = toRecord(manifest.ankh);
|
|
117
|
+
return { ...manifest, ankh: { ...ankh, capabilities } };
|
|
118
|
+
}
|
|
109
119
|
/*** Check whether the Devtools-owned package manifest fields match current policy. */
|
|
110
120
|
export function isManagedPackageContractCurrent(manifest, devtoolsVersion, changesetsConfigExists = false) {
|
|
111
121
|
if (!hasCurrentBunRuntimePolicy(manifest)) {
|
|
@@ -125,6 +135,15 @@ export function isManagedPackageContractCurrent(manifest, devtoolsVersion, chang
|
|
|
125
135
|
hasCurrentChangesetsScripts(scripts, changesetsEnabled) &&
|
|
126
136
|
hasCurrentDevtoolsDependencyPlacement(dependencies, devDependencies, devtoolsVersion));
|
|
127
137
|
}
|
|
138
|
+
/*** Check managed package policy and materialized capability metadata without writing files. */
|
|
139
|
+
async function isManagedPackageContractCurrentAsync(manifest, devtoolsVersion, changesetsConfigExists, targetDirectory) {
|
|
140
|
+
const capabilities = await resolvePackageCapabilitiesAsync(targetDirectory, manifest);
|
|
141
|
+
if (!isManagedPackageContractCurrent(manifest, devtoolsVersion, changesetsConfigExists)) {
|
|
142
|
+
return false;
|
|
143
|
+
}
|
|
144
|
+
return (capabilities === undefined ||
|
|
145
|
+
JSON.stringify(toRecord(manifest.ankh).capabilities) === JSON.stringify(capabilities));
|
|
146
|
+
}
|
|
128
147
|
/*** Read the current Devtools package version used for consumer synchronization. */
|
|
129
148
|
export function readCurrentDevtoolsVersion() {
|
|
130
149
|
const parsed = JSON.parse(readFileSync(new URL('../../../package.json', import.meta.url), 'utf8'));
|
|
@@ -0,0 +1,3 @@
|
|
|
1
|
+
import { type Capability } from '@ankhorage/contracts/capabilities';
|
|
2
|
+
/*** Resolve, validate, and normalize one opted-in package's canonical capability catalog. */
|
|
3
|
+
export declare function resolvePackageCapabilitiesAsync(targetDirectory: string, manifest: Readonly<Record<string, unknown>>): Promise<readonly Capability[] | undefined>;
|
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
/*** Materialize the trusted canonical capability surface for one package checkout. */
|
|
2
|
+
import { access } from 'node:fs/promises';
|
|
3
|
+
import { resolve } from 'node:path';
|
|
4
|
+
import { pathToFileURL } from 'node:url';
|
|
5
|
+
import { isCapability, normalizeCapability, } from '@ankhorage/contracts/capabilities';
|
|
6
|
+
const CAPABILITIES_SOURCE_PATH = 'src/capabilities/index.ts';
|
|
7
|
+
/*** Resolve, validate, and normalize one opted-in package's canonical capability catalog. */
|
|
8
|
+
export async function resolvePackageCapabilitiesAsync(targetDirectory, manifest) {
|
|
9
|
+
const sourcePath = resolve(targetDirectory, CAPABILITIES_SOURCE_PATH);
|
|
10
|
+
try {
|
|
11
|
+
await access(sourcePath);
|
|
12
|
+
}
|
|
13
|
+
catch (error) {
|
|
14
|
+
if (isNodeError(error) && error.code === 'ENOENT') {
|
|
15
|
+
if (!hasCapabilityMetadata(manifest))
|
|
16
|
+
return undefined;
|
|
17
|
+
throw new Error(`package.json ankh.capabilities requires the canonical ${CAPABILITIES_SOURCE_PATH} capability surface.`, { cause: error });
|
|
18
|
+
}
|
|
19
|
+
throw error;
|
|
20
|
+
}
|
|
21
|
+
if (!isRecord(manifest.ankh)) {
|
|
22
|
+
throw new Error(`${CAPABILITIES_SOURCE_PATH} requires package.json ankh discovery metadata for publication.`);
|
|
23
|
+
}
|
|
24
|
+
const source = await import(pathToFileURL(sourcePath).href);
|
|
25
|
+
const catalog = isRecord(source) ? source.CAPABILITIES : undefined;
|
|
26
|
+
if (!Array.isArray(catalog)) {
|
|
27
|
+
throw new Error(`${CAPABILITIES_SOURCE_PATH} must export CAPABILITIES as an array.`);
|
|
28
|
+
}
|
|
29
|
+
const capabilities = catalog.map((capability, index) => {
|
|
30
|
+
if (!isCapability(capability)) {
|
|
31
|
+
throw new Error(`${CAPABILITIES_SOURCE_PATH} CAPABILITIES[${index}] is not a valid Capability.`);
|
|
32
|
+
}
|
|
33
|
+
return normalizeCapability(capability);
|
|
34
|
+
});
|
|
35
|
+
assertUniqueCapabilityIds(capabilities);
|
|
36
|
+
return capabilities;
|
|
37
|
+
}
|
|
38
|
+
/*** Check whether a manifest declares published capability discovery metadata. */
|
|
39
|
+
function hasCapabilityMetadata(manifest) {
|
|
40
|
+
return isRecord(manifest.ankh) && Object.hasOwn(manifest.ankh, 'capabilities');
|
|
41
|
+
}
|
|
42
|
+
/*** Reject duplicate identifiers before serializing a catalog into static package metadata. */
|
|
43
|
+
function assertUniqueCapabilityIds(capabilities) {
|
|
44
|
+
const ids = new Set();
|
|
45
|
+
for (const capability of capabilities) {
|
|
46
|
+
if (ids.has(capability.id)) {
|
|
47
|
+
throw new Error(`Duplicate capability id "${capability.id}" in ${CAPABILITIES_SOURCE_PATH}.`);
|
|
48
|
+
}
|
|
49
|
+
ids.add(capability.id);
|
|
50
|
+
}
|
|
51
|
+
}
|
|
52
|
+
/*** Narrow an unknown value to a JSON object. */
|
|
53
|
+
function isRecord(value) {
|
|
54
|
+
return typeof value === 'object' && value !== null && !Array.isArray(value);
|
|
55
|
+
}
|
|
56
|
+
/*** Narrow an unknown error to a Node error carrying an error code. */
|
|
57
|
+
function isNodeError(error) {
|
|
58
|
+
return error instanceof Error && 'code' in error;
|
|
59
|
+
}
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
import { createRequire } from 'node:module';
|
|
2
|
+
import { format } from 'prettier';
|
|
3
|
+
const require = createRequire(import.meta.url);
|
|
4
|
+
const sharedPrettierConfig = require('./index.cjs');
|
|
5
|
+
/*** Format YAML with the published Devtools Prettier policy. */
|
|
6
|
+
export async function formatYamlAsync(contents) {
|
|
7
|
+
return await format(contents, {
|
|
8
|
+
...sharedPrettierConfig,
|
|
9
|
+
parser: 'yaml',
|
|
10
|
+
});
|
|
11
|
+
}
|
|
@@ -77,6 +77,20 @@ jobs:
|
|
|
77
77
|
echo "No build script found; skipping."
|
|
78
78
|
fi
|
|
79
79
|
|
|
80
|
+
- name: Synchronize package capability metadata
|
|
81
|
+
run: |
|
|
82
|
+
if node -e "const p=require('./package.json'); process.exit(p.ankh === undefined ? 1 : 0)"; then
|
|
83
|
+
if node -e "const p=require('./package.json'); process.exit(p.name === '@ankhorage/devtools' ? 0 : 1)"; then
|
|
84
|
+
bun ./dist/cli/bin/repository.js package sync .
|
|
85
|
+
bun ./dist/cli/bin/repository.js package status .
|
|
86
|
+
else
|
|
87
|
+
bunx --bun --no-install ankhorage-repository package sync .
|
|
88
|
+
bunx --bun --no-install ankhorage-repository package status .
|
|
89
|
+
fi
|
|
90
|
+
else
|
|
91
|
+
echo "No Ankh package metadata found; skipping capability materialization."
|
|
92
|
+
fi
|
|
93
|
+
|
|
80
94
|
- name: Validate release contract
|
|
81
95
|
run: |
|
|
82
96
|
if node -e "const p=require('./package.json'); process.exit(p.name === '@ankhorage/doctor' ? 0 : 1)"; then
|
|
@@ -255,6 +269,32 @@ jobs:
|
|
|
255
269
|
}
|
|
256
270
|
const output = records.sort();
|
|
257
271
|
process.stdout.write(output.length === 0 ? '' : `${output.join('\n')}\n`);
|
|
272
|
+
NODE
|
|
273
|
+
|
|
274
|
+
PACKAGE_NAME="$package_name" node --input-type=module - <<'NODE'
|
|
275
|
+
import { readFileSync } from 'node:fs';
|
|
276
|
+
import { createRequire } from 'node:module';
|
|
277
|
+
import { join } from 'node:path';
|
|
278
|
+
import { pathToFileURL } from 'node:url';
|
|
279
|
+
const name = process.env.PACKAGE_NAME;
|
|
280
|
+
const packageDir = join(process.cwd(), 'node_modules', ...name.split('/'));
|
|
281
|
+
const manifest = JSON.parse(readFileSync(join(packageDir, 'package.json'), 'utf8'));
|
|
282
|
+
if (
|
|
283
|
+
!manifest.ankh ||
|
|
284
|
+
typeof manifest.ankh !== 'object' ||
|
|
285
|
+
!Object.hasOwn(manifest.ankh, 'capabilities')
|
|
286
|
+
) process.exit(0);
|
|
287
|
+
const requireFromPackage = createRequire(join(packageDir, 'package.json'));
|
|
288
|
+
const contractsPath = requireFromPackage.resolve('@ankhorage/contracts/capabilities');
|
|
289
|
+
const { areCapabilitiesEqual, isCapability, normalizeCapability } = await import(pathToFileURL(contractsPath).href);
|
|
290
|
+
const { CAPABILITIES } = await import(`${name}/capabilities`);
|
|
291
|
+
const metadata = manifest.ankh.capabilities;
|
|
292
|
+
if (!Array.isArray(CAPABILITIES) || !Array.isArray(metadata) ||
|
|
293
|
+
!CAPABILITIES.every(isCapability) || !metadata.every(isCapability) ||
|
|
294
|
+
CAPABILITIES.length !== metadata.length ||
|
|
295
|
+
!CAPABILITIES.every((capability, index) => areCapabilitiesEqual(normalizeCapability(capability), metadata[index]))) {
|
|
296
|
+
throw new Error('Packed package.json ankh.capabilities must exactly match the public CAPABILITIES catalog.');
|
|
297
|
+
}
|
|
258
298
|
NODE
|
|
259
299
|
|
|
260
300
|
while IFS='|' read -r loader specifier; do
|
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import { readFile } from 'node:fs/promises';
|
|
2
2
|
import { REPOSITORY_RULE_METADATA } from '@ankhorage/rules-repository';
|
|
3
|
+
import { formatYamlAsync } from '../prettier/formatYamlAsync.js';
|
|
3
4
|
/*** Renders one workflow template with the canonical runtime, Doctor, and Changesets policy. */
|
|
4
5
|
export async function renderWorkflowAsync(sourceUrl, policy) {
|
|
5
6
|
const template = await readFile(sourceUrl, 'utf8');
|
|
@@ -13,7 +14,7 @@ export async function renderWorkflowAsync(sourceUrl, policy) {
|
|
|
13
14
|
.replaceAll('__ANKH_APM_RELEASE_COMMAND__', policy.apmReleaseCommand ?? './node_modules/.bin/ankhorage-apm-release')
|
|
14
15
|
.replaceAll('__ANKH_STRUCTURE_RELEASE_COMMAND__', policy.structureReleaseCommand ?? './node_modules/.bin/ankhorage-structure')
|
|
15
16
|
.replaceAll(NODE_VERSION_TOKEN, policy.nodeVersion);
|
|
16
|
-
return `${rendered.trimEnd()}\n
|
|
17
|
+
return await formatYamlAsync(`${rendered.trimEnd()}\n`);
|
|
17
18
|
}
|
|
18
19
|
const BUN_VERSION_TOKEN = '__ANKH_BUN_VERSION__';
|
|
19
20
|
const CHANGESETS_PUBLISH_COMMAND_TOKEN = '__ANKH_CHANGESETS_PUBLISH_COMMAND__';
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@ankhorage/devtools",
|
|
3
|
-
"version": "2.
|
|
3
|
+
"version": "2.3.6",
|
|
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",
|
|
@@ -431,7 +431,8 @@
|
|
|
431
431
|
"ankhorage-knip": "./dist/cli/bin/knip.js",
|
|
432
432
|
"ankhorage-prettier": "./dist/cli/bin/prettier.js",
|
|
433
433
|
"ankhorage-apm-release": "./dist/cli/bin/apm-release.js",
|
|
434
|
-
"ankhorage-structure": "./dist/cli/bin/structure.js"
|
|
434
|
+
"ankhorage-structure": "./dist/cli/bin/structure.js",
|
|
435
|
+
"ankhorage-repository": "./dist/cli/bin/repository.js"
|
|
435
436
|
},
|
|
436
437
|
"exports": {
|
|
437
438
|
"./cli": {
|
|
@@ -490,7 +491,7 @@
|
|
|
490
491
|
},
|
|
491
492
|
"dependencies": {
|
|
492
493
|
"@ankhorage/apm": "^0.8.14",
|
|
493
|
-
"@ankhorage/contracts": "^24.1
|
|
494
|
+
"@ankhorage/contracts": "^24.2.1",
|
|
494
495
|
"@ankhorage/project-detector": "^0.3.4",
|
|
495
496
|
"@ankhorage/rules-repository": "^0.2.0",
|
|
496
497
|
"@ankhorage/utility": "^0.5.5",
|
|
@@ -514,9 +515,9 @@
|
|
|
514
515
|
"typescript-eslint": "^8.71.1"
|
|
515
516
|
},
|
|
516
517
|
"devDependencies": {
|
|
517
|
-
"@ankhorage/paradox": "^0.
|
|
518
|
-
"@ankhorage/ankh": "^0.12.
|
|
519
|
-
"@ankhorage/doctor": "0.
|
|
518
|
+
"@ankhorage/paradox": "^0.3.1",
|
|
519
|
+
"@ankhorage/ankh": "^0.12.2",
|
|
520
|
+
"@ankhorage/doctor": "0.14.2",
|
|
520
521
|
"@techstark/opencv-js": "^5.0.0-release.1",
|
|
521
522
|
"@types/bun": "^1.4.2",
|
|
522
523
|
"@types/node": "^26.6.4",
|