@ankhorage/devtools 2.7.0 → 2.8.1
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 +18 -12
- package/dist/features/repository-metadata/application/readRepositoryMetadataFactAsync.d.ts +9 -0
- package/dist/features/repository-metadata/application/readRepositoryMetadataFactAsync.js +191 -0
- package/dist/features/repository-metadata/application/runRepositoryMetadataCommandAsync.js +4 -137
- package/dist/internal/readmeDocs.d.ts +2 -1
- package/dist/internal/readmeDocs.js +4 -4
- package/dist/tools/agents/index.js +6 -10
- package/dist/tools/agents/renderRepositorySectionsAsync.d.ts +7 -0
- package/dist/tools/agents/renderRepositorySectionsAsync.js +86 -0
- package/dist/tools/workflows/files/release.yml +16 -3
- package/package.json +13 -13
package/README.md
CHANGED
|
@@ -1,11 +1,13 @@
|
|
|
1
1
|
<!-- markdownlint-disable MD013 MD033 -->
|
|
2
2
|
<!-- This file is generated by Paradox. Do not edit manually. -->
|
|
3
3
|
|
|
4
|
-
#
|
|
4
|
+
# Ankhorage Devtools
|
|
5
5
|
|
|
6
|
-
         
|
|
7
7
|
|
|
8
|
-
|
|
8
|
+
Owns shared repository automation, managed development tooling, workflows, and agent standards for Ankhorage TypeScript projects.
|
|
9
|
+
|
|
10
|
+
Keep standalone repositories aligned through released, reusable tooling instead of copied project-specific automation.
|
|
9
11
|
|
|
10
12
|
## Usage
|
|
11
13
|
|
|
@@ -35,16 +37,9 @@ export default createConfig({
|
|
|
35
37
|
|
|
36
38
|
This package contains 1 additional example. See the generated documentation for the complete set.
|
|
37
39
|
|
|
38
|
-
##
|
|
40
|
+
## Documentation
|
|
39
41
|
|
|
40
|
-
|
|
41
|
-
- [Public API reference](././paradox/exports.md)
|
|
42
|
-
- [Component registry](././paradox/components.md)
|
|
43
|
-
- [Architecture overview](././paradox/diagrams/architecture-overview.mmd)
|
|
44
|
-
- [Module relationships](././paradox/diagrams/module-relationships.mmd)
|
|
45
|
-
- [Export graph](././paradox/diagrams/export-graph.mmd)
|
|
46
|
-
- [createKnipConfig sequence](././paradox/diagrams/sequences/create-knip-config.mmd)
|
|
47
|
-
- [createKnipMonorepoConfig sequence](././paradox/diagrams/sequences/create-knip-monorepo-config.mmd)
|
|
42
|
+
Open `./paradox/index.html` locally in your browser to browse the complete documentation.
|
|
48
43
|
|
|
49
44
|
## Public API
|
|
50
45
|
|
|
@@ -92,3 +87,14 @@ Source: `src/features/apm-release-validation/composition/validatePackedApmReleas
|
|
|
92
87
|
Related symbols: `ApmReleaseValidationOptions`, `ApmReleaseValidationResult`
|
|
93
88
|
|
|
94
89
|
</details>
|
|
90
|
+
|
|
91
|
+
## Contributors
|
|
92
|
+
|
|
93
|
+
<!-- readme: contributors -start -->
|
|
94
|
+
<!-- readme: contributors -end -->
|
|
95
|
+
|
|
96
|
+
## Donation
|
|
97
|
+
|
|
98
|
+
If this project is useful to you, you can support its continued development.
|
|
99
|
+
|
|
100
|
+
[Support @ankhorage](https://github.com/sponsors/ankhorage)
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
import type { RepositoryMetadata } from '@ankhorage/contracts/metadata';
|
|
2
|
+
export interface RepositoryMetadataFact {
|
|
3
|
+
readonly document: RepositoryMetadata | undefined;
|
|
4
|
+
readonly exists: boolean;
|
|
5
|
+
readonly path: string;
|
|
6
|
+
readonly profile: 'non-source' | 'source';
|
|
7
|
+
}
|
|
8
|
+
/*** Read canonical repository metadata as inert JSON from the profile-owned local path. */
|
|
9
|
+
export declare function readRepositoryMetadataFactAsync(targetDirectory: string): Promise<RepositoryMetadataFact>;
|
|
@@ -0,0 +1,191 @@
|
|
|
1
|
+
import { access, readFile } from 'node:fs/promises';
|
|
2
|
+
import { join } from 'node:path';
|
|
3
|
+
import { REPOSITORY_RULE_METADATA } from '@ankhorage/rules-repository';
|
|
4
|
+
import { isRecord } from '@ankhorage/utility/object';
|
|
5
|
+
/*** Read canonical repository metadata as inert JSON from the profile-owned local path. */
|
|
6
|
+
export async function readRepositoryMetadataFactAsync(targetDirectory) {
|
|
7
|
+
const profile = (await pathExistsAsync(join(targetDirectory, 'src'))) ? 'source' : 'non-source';
|
|
8
|
+
const path = profile === 'source'
|
|
9
|
+
? REPOSITORY_RULE_METADATA.metadata.profiles.source.canonicalPath
|
|
10
|
+
: REPOSITORY_RULE_METADATA.metadata.profiles.nonSource.canonicalPath;
|
|
11
|
+
const metadataPath = join(targetDirectory, path);
|
|
12
|
+
if (!(await pathExistsAsync(metadataPath))) {
|
|
13
|
+
return { document: undefined, exists: false, path, profile };
|
|
14
|
+
}
|
|
15
|
+
return {
|
|
16
|
+
document: parseRepositoryMetadata(await readFile(metadataPath, 'utf8')),
|
|
17
|
+
exists: true,
|
|
18
|
+
path,
|
|
19
|
+
profile,
|
|
20
|
+
};
|
|
21
|
+
}
|
|
22
|
+
/*** Decode a complete portable metadata document without executing repository-owned code. */
|
|
23
|
+
function parseRepositoryMetadata(text) {
|
|
24
|
+
const parsed = parseJsonDocument(text);
|
|
25
|
+
if (!isRecord(parsed) || parsed.schemaVersion !== 1 || !isMetadataKind(parsed.kind)) {
|
|
26
|
+
return undefined;
|
|
27
|
+
}
|
|
28
|
+
if (typeof parsed.title !== 'string' ||
|
|
29
|
+
typeof parsed.summary !== 'string' ||
|
|
30
|
+
typeof parsed.purpose !== 'string' ||
|
|
31
|
+
!hasValidOptionalFields(parsed)) {
|
|
32
|
+
return undefined;
|
|
33
|
+
}
|
|
34
|
+
return {
|
|
35
|
+
schemaVersion: 1,
|
|
36
|
+
kind: parsed.kind,
|
|
37
|
+
title: parsed.title,
|
|
38
|
+
summary: parsed.summary,
|
|
39
|
+
purpose: parsed.purpose,
|
|
40
|
+
...optionalMetadataFields(parsed),
|
|
41
|
+
};
|
|
42
|
+
}
|
|
43
|
+
/*** Parse authored JSON without leaking parser-specific failures across the metadata boundary. */
|
|
44
|
+
function parseJsonDocument(text) {
|
|
45
|
+
try {
|
|
46
|
+
return JSON.parse(text);
|
|
47
|
+
}
|
|
48
|
+
catch {
|
|
49
|
+
return undefined;
|
|
50
|
+
}
|
|
51
|
+
}
|
|
52
|
+
/*** Reject malformed recognized fields instead of silently discarding authored facts. */
|
|
53
|
+
function hasValidOptionalFields(metadata) {
|
|
54
|
+
return ((metadata.domain === undefined || typeof metadata.domain === 'string') &&
|
|
55
|
+
hasOptionalStringArray(metadata.responsibilities) &&
|
|
56
|
+
hasOptionalStringArray(metadata.boundaries) &&
|
|
57
|
+
hasOptionalStringArray(metadata.audience) &&
|
|
58
|
+
hasOptionalStringArray(metadata.useCases) &&
|
|
59
|
+
hasValidArchitecture(metadata.architecture) &&
|
|
60
|
+
hasValidImplementations(metadata.implements) &&
|
|
61
|
+
hasValidConstraints(metadata.constraints));
|
|
62
|
+
}
|
|
63
|
+
/*** Preserve optional Contract fields after their complete shape has been verified. */
|
|
64
|
+
function optionalMetadataFields(metadata) {
|
|
65
|
+
return {
|
|
66
|
+
...(typeof metadata.domain === 'string' ? { domain: metadata.domain } : {}),
|
|
67
|
+
...optionalTextCollections(metadata),
|
|
68
|
+
...optionalArchitectureField(metadata.architecture),
|
|
69
|
+
...optionalImplementsField(metadata.implements),
|
|
70
|
+
...optionalConstraintsField(metadata.constraints),
|
|
71
|
+
};
|
|
72
|
+
}
|
|
73
|
+
/*** Read optional authored text collections from a previously validated document. */
|
|
74
|
+
function optionalTextCollections(metadata) {
|
|
75
|
+
const responsibilities = readStringArray(metadata.responsibilities);
|
|
76
|
+
const boundaries = readStringArray(metadata.boundaries);
|
|
77
|
+
const audience = readStringArray(metadata.audience);
|
|
78
|
+
const useCases = readStringArray(metadata.useCases);
|
|
79
|
+
return {
|
|
80
|
+
...(responsibilities === undefined ? {} : { responsibilities }),
|
|
81
|
+
...(boundaries === undefined ? {} : { boundaries }),
|
|
82
|
+
...(audience === undefined ? {} : { audience }),
|
|
83
|
+
...(useCases === undefined ? {} : { useCases }),
|
|
84
|
+
};
|
|
85
|
+
}
|
|
86
|
+
/*** Read an optional architecture fact from a previously validated document. */
|
|
87
|
+
function optionalArchitectureField(value) {
|
|
88
|
+
if (!isRecord(value))
|
|
89
|
+
return {};
|
|
90
|
+
const invariants = readStringArray(value.invariants);
|
|
91
|
+
const architecture = {
|
|
92
|
+
...(typeof value.role === 'string' ? { role: value.role } : {}),
|
|
93
|
+
...(invariants === undefined ? {} : { invariants }),
|
|
94
|
+
};
|
|
95
|
+
return Object.keys(architecture).length > 0 ? { architecture } : {};
|
|
96
|
+
}
|
|
97
|
+
/*** Read implementation references from a previously validated document. */
|
|
98
|
+
function optionalImplementsField(value) {
|
|
99
|
+
if (!Array.isArray(value))
|
|
100
|
+
return {};
|
|
101
|
+
return {
|
|
102
|
+
implements: value.flatMap((reference) => {
|
|
103
|
+
const implementation = parseImplementationReference(reference);
|
|
104
|
+
return implementation === undefined ? [] : [implementation];
|
|
105
|
+
}),
|
|
106
|
+
};
|
|
107
|
+
}
|
|
108
|
+
/*** Decode one validated portable implementation reference. */
|
|
109
|
+
function parseImplementationReference(value) {
|
|
110
|
+
if (!isRecord(value) || typeof value.packageName !== 'string')
|
|
111
|
+
return undefined;
|
|
112
|
+
if (value.subpath !== undefined && typeof value.subpath !== 'string')
|
|
113
|
+
return undefined;
|
|
114
|
+
if (value.interfaceId !== undefined && typeof value.interfaceId !== 'string')
|
|
115
|
+
return undefined;
|
|
116
|
+
return {
|
|
117
|
+
packageName: value.packageName,
|
|
118
|
+
...(typeof value.subpath === 'string' ? { subpath: value.subpath } : {}),
|
|
119
|
+
...(typeof value.interfaceId === 'string' ? { interfaceId: value.interfaceId } : {}),
|
|
120
|
+
};
|
|
121
|
+
}
|
|
122
|
+
/*** Read optional operational constraints from a previously validated document. */
|
|
123
|
+
function optionalConstraintsField(value) {
|
|
124
|
+
if (!isRecord(value))
|
|
125
|
+
return {};
|
|
126
|
+
const constraints = {
|
|
127
|
+
...(readStringArray(value.platforms) === undefined
|
|
128
|
+
? {}
|
|
129
|
+
: { platforms: readStringArray(value.platforms) }),
|
|
130
|
+
...(readStringArray(value.configuration) === undefined
|
|
131
|
+
? {}
|
|
132
|
+
: { configuration: readStringArray(value.configuration) }),
|
|
133
|
+
...(readStringArray(value.security) === undefined
|
|
134
|
+
? {}
|
|
135
|
+
: { security: readStringArray(value.security) }),
|
|
136
|
+
...(readStringArray(value.limitations) === undefined
|
|
137
|
+
? {}
|
|
138
|
+
: { limitations: readStringArray(value.limitations) }),
|
|
139
|
+
};
|
|
140
|
+
return Object.keys(constraints).length > 0 ? { constraints } : {};
|
|
141
|
+
}
|
|
142
|
+
/*** Check whether an optional value is absent or a complete Contract-compatible string array. */
|
|
143
|
+
function hasOptionalStringArray(value) {
|
|
144
|
+
return value === undefined || readStringArray(value) !== undefined;
|
|
145
|
+
}
|
|
146
|
+
/*** Check an optional architecture field without accepting malformed child values. */
|
|
147
|
+
function hasValidArchitecture(value) {
|
|
148
|
+
return (value === undefined ||
|
|
149
|
+
(isRecord(value) &&
|
|
150
|
+
(value.role === undefined || typeof value.role === 'string') &&
|
|
151
|
+
hasOptionalStringArray(value.invariants)));
|
|
152
|
+
}
|
|
153
|
+
/*** Check optional implementation references without losing malformed entries. */
|
|
154
|
+
function hasValidImplementations(value) {
|
|
155
|
+
return (value === undefined ||
|
|
156
|
+
(Array.isArray(value) &&
|
|
157
|
+
value.every((reference) => parseImplementationReference(reference) !== undefined)));
|
|
158
|
+
}
|
|
159
|
+
/*** Check optional constraint fields without accepting malformed child values. */
|
|
160
|
+
function hasValidConstraints(value) {
|
|
161
|
+
return (value === undefined ||
|
|
162
|
+
(isRecord(value) &&
|
|
163
|
+
hasOptionalStringArray(value.platforms) &&
|
|
164
|
+
hasOptionalStringArray(value.configuration) &&
|
|
165
|
+
hasOptionalStringArray(value.security) &&
|
|
166
|
+
hasOptionalStringArray(value.limitations)));
|
|
167
|
+
}
|
|
168
|
+
/*** Read one Contract-compatible string-array shape from authored JSON. */
|
|
169
|
+
function readStringArray(value) {
|
|
170
|
+
return Array.isArray(value) && value.every((entry) => typeof entry === 'string')
|
|
171
|
+
? value
|
|
172
|
+
: undefined;
|
|
173
|
+
}
|
|
174
|
+
/*** Recognize the portable Contract's closed metadata-kind vocabulary. */
|
|
175
|
+
function isMetadataKind(value) {
|
|
176
|
+
return (typeof value === 'string' &&
|
|
177
|
+
[
|
|
178
|
+
'adapter',
|
|
179
|
+
'application',
|
|
180
|
+
'configuration',
|
|
181
|
+
'contract',
|
|
182
|
+
'infrastructure',
|
|
183
|
+
'library',
|
|
184
|
+
'tooling',
|
|
185
|
+
'website',
|
|
186
|
+
].includes(value));
|
|
187
|
+
}
|
|
188
|
+
/*** Test one local path without shelling out or consulting external state. */
|
|
189
|
+
async function pathExistsAsync(path) {
|
|
190
|
+
return await access(path).then(() => true, () => false);
|
|
191
|
+
}
|
|
@@ -1,19 +1,20 @@
|
|
|
1
1
|
import { access, mkdir, readFile, writeFile } from 'node:fs/promises';
|
|
2
2
|
import { dirname, join, resolve } from 'node:path';
|
|
3
|
-
import { evaluateRepositoryMetadataPreflight
|
|
3
|
+
import { evaluateRepositoryMetadataPreflight } from '@ankhorage/rules-repository';
|
|
4
4
|
import { isRecord } from '@ankhorage/utility/object';
|
|
5
|
+
import { readRepositoryMetadataFactAsync } from './readRepositoryMetadataFactAsync.js';
|
|
5
6
|
/*** Initialize or inspect authored repository metadata without turning it into an enforcement gate. */
|
|
6
7
|
export async function runRepositoryMetadataCommandAsync(operation, argv, context) {
|
|
7
8
|
try {
|
|
8
9
|
const input = parseMetadataArguments(argv, operation === 'init');
|
|
9
10
|
const targetDirectory = resolve(context.cwd, input.targetPath ?? '.');
|
|
10
11
|
await assertDirectoryAsync(targetDirectory);
|
|
11
|
-
const fact = await
|
|
12
|
+
const fact = await readRepositoryMetadataFactAsync(targetDirectory);
|
|
12
13
|
if (operation === 'init' && !fact.exists) {
|
|
13
14
|
const result = await initializeMetadataAsync(targetDirectory, fact.path, input.dryRun);
|
|
14
15
|
context.writeStdout(`${result} ${fact.path}\n`);
|
|
15
16
|
}
|
|
16
|
-
const status = await
|
|
17
|
+
const status = await readRepositoryMetadataFactAsync(targetDirectory);
|
|
17
18
|
const evaluation = evaluateRepositoryMetadataPreflight({
|
|
18
19
|
cliCommands: [],
|
|
19
20
|
imports: [],
|
|
@@ -57,22 +58,6 @@ function parseMetadataArguments(argv, allowDryRun) {
|
|
|
57
58
|
async function assertDirectoryAsync(targetDirectory) {
|
|
58
59
|
await access(targetDirectory);
|
|
59
60
|
}
|
|
60
|
-
/*** Discover the profile-owned metadata location and parse only structurally recognizable JSON. */
|
|
61
|
-
async function readMetadataFactAsync(targetDirectory) {
|
|
62
|
-
const profile = (await pathExistsAsync(join(targetDirectory, 'src'))) ? 'source' : 'non-source';
|
|
63
|
-
const path = profile === 'source'
|
|
64
|
-
? REPOSITORY_RULE_METADATA.metadata.profiles.source.canonicalPath
|
|
65
|
-
: REPOSITORY_RULE_METADATA.metadata.profiles.nonSource.canonicalPath;
|
|
66
|
-
const metadataPath = join(targetDirectory, path);
|
|
67
|
-
if (!(await pathExistsAsync(metadataPath)))
|
|
68
|
-
return { document: undefined, exists: false, path, profile };
|
|
69
|
-
return {
|
|
70
|
-
document: parseRepositoryMetadata(await readFile(metadataPath, 'utf8')),
|
|
71
|
-
exists: true,
|
|
72
|
-
path,
|
|
73
|
-
profile,
|
|
74
|
-
};
|
|
75
|
-
}
|
|
76
61
|
/*** Create an intentionally incomplete authored template only when metadata is absent. */
|
|
77
62
|
async function initializeMetadataAsync(targetDirectory, relativePath, dryRun) {
|
|
78
63
|
const destination = join(targetDirectory, relativePath);
|
|
@@ -100,124 +85,6 @@ async function readManifestAsync(targetDirectory) {
|
|
|
100
85
|
const parsed = JSON.parse(await readFile(manifestPath, 'utf8'));
|
|
101
86
|
return isRecord(parsed) ? parsed : {};
|
|
102
87
|
}
|
|
103
|
-
/*** Decode a document enough for Rules to produce diagnostic findings without claiming semantic truth. */
|
|
104
|
-
function parseRepositoryMetadata(text) {
|
|
105
|
-
const parsed = JSON.parse(text);
|
|
106
|
-
if (!isRecord(parsed) || parsed.schemaVersion !== 1 || !isMetadataKind(parsed.kind))
|
|
107
|
-
return undefined;
|
|
108
|
-
if (typeof parsed.title !== 'string' ||
|
|
109
|
-
typeof parsed.summary !== 'string' ||
|
|
110
|
-
typeof parsed.purpose !== 'string') {
|
|
111
|
-
return undefined;
|
|
112
|
-
}
|
|
113
|
-
return {
|
|
114
|
-
schemaVersion: 1,
|
|
115
|
-
kind: parsed.kind,
|
|
116
|
-
title: parsed.title,
|
|
117
|
-
summary: parsed.summary,
|
|
118
|
-
purpose: parsed.purpose,
|
|
119
|
-
...optionalMetadataFields(parsed),
|
|
120
|
-
};
|
|
121
|
-
}
|
|
122
|
-
/*** Preserve recognizable optional Contract fields so Rules can report their semantic findings. */
|
|
123
|
-
function optionalMetadataFields(metadata) {
|
|
124
|
-
return {
|
|
125
|
-
...(typeof metadata.domain === 'string' ? { domain: metadata.domain } : {}),
|
|
126
|
-
...optionalTextCollections(metadata),
|
|
127
|
-
...optionalArchitectureField(metadata.architecture),
|
|
128
|
-
...optionalImplementsField(metadata.implements),
|
|
129
|
-
...optionalConstraintsField(metadata.constraints),
|
|
130
|
-
};
|
|
131
|
-
}
|
|
132
|
-
/*** Read optional authored text collections without widening untrusted JSON values. */
|
|
133
|
-
function optionalTextCollections(metadata) {
|
|
134
|
-
const responsibilities = readStringArray(metadata.responsibilities);
|
|
135
|
-
const boundaries = readStringArray(metadata.boundaries);
|
|
136
|
-
const audience = readStringArray(metadata.audience);
|
|
137
|
-
const useCases = readStringArray(metadata.useCases);
|
|
138
|
-
return {
|
|
139
|
-
...(responsibilities === undefined ? {} : { responsibilities }),
|
|
140
|
-
...(boundaries === undefined ? {} : { boundaries }),
|
|
141
|
-
...(audience === undefined ? {} : { audience }),
|
|
142
|
-
...(useCases === undefined ? {} : { useCases }),
|
|
143
|
-
};
|
|
144
|
-
}
|
|
145
|
-
/*** Read an optional architecture fact only when all recognized subfields are safely shaped. */
|
|
146
|
-
function optionalArchitectureField(value) {
|
|
147
|
-
if (!isRecord(value))
|
|
148
|
-
return {};
|
|
149
|
-
const architecture = {
|
|
150
|
-
...(typeof value.role === 'string' ? { role: value.role } : {}),
|
|
151
|
-
...(Array.isArray(value.invariants) &&
|
|
152
|
-
value.invariants.every((item) => typeof item === 'string')
|
|
153
|
-
? { invariants: value.invariants }
|
|
154
|
-
: {}),
|
|
155
|
-
};
|
|
156
|
-
return Object.keys(architecture).length > 0 ? { architecture } : {};
|
|
157
|
-
}
|
|
158
|
-
/*** Read implementation references so their public-shape rules remain observable to authors. */
|
|
159
|
-
function optionalImplementsField(value) {
|
|
160
|
-
if (!Array.isArray(value))
|
|
161
|
-
return {};
|
|
162
|
-
const implementations = value.map(parseImplementationReference);
|
|
163
|
-
return implementations.every((implementation) => implementation !== undefined)
|
|
164
|
-
? { implements: implementations }
|
|
165
|
-
: {};
|
|
166
|
-
}
|
|
167
|
-
/*** Decode one Contract-shaped implementation reference from authored JSON. */
|
|
168
|
-
function parseImplementationReference(value) {
|
|
169
|
-
if (!isRecord(value) || typeof value.packageName !== 'string')
|
|
170
|
-
return undefined;
|
|
171
|
-
if (value.subpath !== undefined && typeof value.subpath !== 'string')
|
|
172
|
-
return undefined;
|
|
173
|
-
if (value.interfaceId !== undefined && typeof value.interfaceId !== 'string')
|
|
174
|
-
return undefined;
|
|
175
|
-
return {
|
|
176
|
-
packageName: value.packageName,
|
|
177
|
-
...(typeof value.subpath === 'string' ? { subpath: value.subpath } : {}),
|
|
178
|
-
...(typeof value.interfaceId === 'string' ? { interfaceId: value.interfaceId } : {}),
|
|
179
|
-
};
|
|
180
|
-
}
|
|
181
|
-
/*** Read optional platform and operational constraints without accepting malformed child lists. */
|
|
182
|
-
function optionalConstraintsField(value) {
|
|
183
|
-
if (!isRecord(value))
|
|
184
|
-
return {};
|
|
185
|
-
const constraints = {
|
|
186
|
-
...(readStringArray(value.platforms) === undefined
|
|
187
|
-
? {}
|
|
188
|
-
: { platforms: readStringArray(value.platforms) }),
|
|
189
|
-
...(readStringArray(value.configuration) === undefined
|
|
190
|
-
? {}
|
|
191
|
-
: { configuration: readStringArray(value.configuration) }),
|
|
192
|
-
...(readStringArray(value.security) === undefined
|
|
193
|
-
? {}
|
|
194
|
-
: { security: readStringArray(value.security) }),
|
|
195
|
-
...(readStringArray(value.limitations) === undefined
|
|
196
|
-
? {}
|
|
197
|
-
: { limitations: readStringArray(value.limitations) }),
|
|
198
|
-
};
|
|
199
|
-
return Object.keys(constraints).length > 0 ? { constraints } : {};
|
|
200
|
-
}
|
|
201
|
-
/*** Read one Contract-compatible string-array shape from authored JSON. */
|
|
202
|
-
function readStringArray(value) {
|
|
203
|
-
return Array.isArray(value) && value.every((entry) => typeof entry === 'string')
|
|
204
|
-
? value
|
|
205
|
-
: undefined;
|
|
206
|
-
}
|
|
207
|
-
/*** Recognize the portable Contract's closed metadata-kind vocabulary. */
|
|
208
|
-
function isMetadataKind(value) {
|
|
209
|
-
return (typeof value === 'string' &&
|
|
210
|
-
[
|
|
211
|
-
'adapter',
|
|
212
|
-
'application',
|
|
213
|
-
'configuration',
|
|
214
|
-
'contract',
|
|
215
|
-
'infrastructure',
|
|
216
|
-
'library',
|
|
217
|
-
'tooling',
|
|
218
|
-
'website',
|
|
219
|
-
].includes(value));
|
|
220
|
-
}
|
|
221
88
|
/*** Identify human-authored fields that deliberately remain absent from the bootstrap template. */
|
|
222
89
|
function authoredTasks(document) {
|
|
223
90
|
if (document === undefined)
|
|
@@ -1 +1,2 @@
|
|
|
1
|
-
|
|
1
|
+
/*** Checks generated README markers using the title owned by repository metadata. */
|
|
2
|
+
export declare function getReadmeDocumentationErrors(readmeContents: string, expectedTitle: string): string[];
|
|
@@ -1,15 +1,15 @@
|
|
|
1
1
|
const REQUIRED_README_SNIPPETS = [
|
|
2
2
|
'<!-- This file is generated by Paradox. Do not edit manually. -->',
|
|
3
|
-
'# @ankhorage/devtools',
|
|
4
3
|
'## Usage',
|
|
5
4
|
'ankh devtools --help',
|
|
6
5
|
'Standalone package ESLint configuration',
|
|
7
6
|
'export default createConfig({',
|
|
8
|
-
'##
|
|
7
|
+
'## Documentation',
|
|
9
8
|
'paradox/index.html',
|
|
10
9
|
];
|
|
11
|
-
|
|
12
|
-
|
|
10
|
+
/*** Checks generated README markers using the title owned by repository metadata. */
|
|
11
|
+
export function getReadmeDocumentationErrors(readmeContents, expectedTitle) {
|
|
12
|
+
return [`# ${expectedTitle}`, ...REQUIRED_README_SNIPPETS].flatMap((snippet) => readmeContents.includes(snippet)
|
|
13
13
|
? []
|
|
14
14
|
: [`README.md is missing required documentation snippet: ${snippet}`]);
|
|
15
15
|
}
|
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import { readFile } from 'node:fs/promises';
|
|
2
2
|
import { resolve } from 'node:path';
|
|
3
|
+
import { renderRepositorySectionsAsync } from './renderRepositorySectionsAsync.js';
|
|
3
4
|
export const agentsManagedFiles = [
|
|
4
5
|
{
|
|
5
6
|
relativePath: 'AGENTS.md',
|
|
@@ -19,6 +20,10 @@ async function renderAgentsFile(targetDirectory) {
|
|
|
19
20
|
const manifest = await readPackageManifest(targetDirectory);
|
|
20
21
|
const packageName = readNonEmptyString(manifest.name) ?? 'Package name not declared';
|
|
21
22
|
const description = readNonEmptyString(manifest.description) ?? 'No package description is declared.';
|
|
23
|
+
const repositorySections = await renderRepositorySectionsAsync(targetDirectory, {
|
|
24
|
+
description,
|
|
25
|
+
packageName,
|
|
26
|
+
});
|
|
22
27
|
const sections = [
|
|
23
28
|
renderCurrentArchitectureInstructions(),
|
|
24
29
|
renderStandaloneRepositoryInstructions(),
|
|
@@ -31,12 +36,7 @@ async function renderAgentsFile(targetDirectory) {
|
|
|
31
36
|
|
|
32
37
|
<!-- This file is managed by @ankhorage/devtools. -->
|
|
33
38
|
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
Package: \`${escapeInlineCode(packageName)}\`
|
|
37
|
-
|
|
38
|
-
${description}
|
|
39
|
-
|
|
39
|
+
${repositorySections}
|
|
40
40
|
${sections}`;
|
|
41
41
|
}
|
|
42
42
|
/*** Render the current-architecture policy shared by every managed repository. */
|
|
@@ -159,10 +159,6 @@ async function readPackageManifest(targetDirectory) {
|
|
|
159
159
|
throw error;
|
|
160
160
|
}
|
|
161
161
|
}
|
|
162
|
-
/*** Escape inline-code delimiters before interpolating repository metadata into Markdown. */
|
|
163
|
-
function escapeInlineCode(value) {
|
|
164
|
-
return value.replaceAll('`', '\\`');
|
|
165
|
-
}
|
|
166
162
|
/*** Check whether an unknown failure carries a Node.js error code. */
|
|
167
163
|
function isNodeError(error) {
|
|
168
164
|
return error instanceof Error && 'code' in error;
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
interface RepositoryIdentity {
|
|
2
|
+
readonly description: string;
|
|
3
|
+
readonly packageName: string;
|
|
4
|
+
}
|
|
5
|
+
/*** Render curated repository scope when valid metadata exists, preserving the manifest fallback. */
|
|
6
|
+
export declare function renderRepositorySectionsAsync(targetDirectory: string, identity: RepositoryIdentity): Promise<string>;
|
|
7
|
+
export {};
|
|
@@ -0,0 +1,86 @@
|
|
|
1
|
+
import { evaluateRepositoryMetadataPreflight } from '@ankhorage/rules-repository';
|
|
2
|
+
import { readRepositoryMetadataFactAsync } from '../../features/repository-metadata/application/readRepositoryMetadataFactAsync.js';
|
|
3
|
+
/*** Render curated repository scope when valid metadata exists, preserving the manifest fallback. */
|
|
4
|
+
export async function renderRepositorySectionsAsync(targetDirectory, identity) {
|
|
5
|
+
const fact = await readRepositoryMetadataFactAsync(targetDirectory);
|
|
6
|
+
if (!fact.exists) {
|
|
7
|
+
return renderFallbackRepositorySection(identity);
|
|
8
|
+
}
|
|
9
|
+
const evaluation = evaluateRepositoryMetadataPreflight({
|
|
10
|
+
cliCommands: [],
|
|
11
|
+
imports: [],
|
|
12
|
+
metadata: { ...fact, eligibility: 'applicable', managed: true },
|
|
13
|
+
packageJson: { dependencies: [], exports: [], fields: {}, scripts: {} },
|
|
14
|
+
paths: [],
|
|
15
|
+
workflowBunVersions: {},
|
|
16
|
+
});
|
|
17
|
+
if (fact.document === undefined || evaluation.findings.length > 0) {
|
|
18
|
+
const messages = evaluation.findings.map(({ message }) => message).join('; ');
|
|
19
|
+
throw new Error(`Invalid repository metadata at ${fact.path}: ${messages || 'document does not match the published contract'}`);
|
|
20
|
+
}
|
|
21
|
+
return renderCuratedRepositorySections(identity.packageName, fact.document);
|
|
22
|
+
}
|
|
23
|
+
/*** Render the transition-safe package-manifest fallback when canonical metadata is absent. */
|
|
24
|
+
function renderFallbackRepositorySection(identity) {
|
|
25
|
+
return `## Repository
|
|
26
|
+
|
|
27
|
+
Package: \`${escapeInlineCode(identity.packageName)}\`
|
|
28
|
+
|
|
29
|
+
${escapeMarkdownText(identity.description)}
|
|
30
|
+
|
|
31
|
+
`;
|
|
32
|
+
}
|
|
33
|
+
/*** Render authored purpose, ownership, boundaries, audience, and architectural invariants. */
|
|
34
|
+
function renderCuratedRepositorySections(packageName, metadata) {
|
|
35
|
+
const repositoryDetails = [
|
|
36
|
+
`Package: \`${escapeInlineCode(packageName)}\``,
|
|
37
|
+
`Title: ${escapeMarkdownText(metadata.title)}`,
|
|
38
|
+
escapeMarkdownText(metadata.summary),
|
|
39
|
+
`Purpose: ${escapeMarkdownText(metadata.purpose)}`,
|
|
40
|
+
renderList('Audience', metadata.audience),
|
|
41
|
+
]
|
|
42
|
+
.filter((value) => value !== '')
|
|
43
|
+
.join('\n\n');
|
|
44
|
+
const scopeDetails = [
|
|
45
|
+
renderList('Responsibilities', metadata.responsibilities),
|
|
46
|
+
renderList('Boundaries', metadata.boundaries),
|
|
47
|
+
metadata.architecture?.role === undefined
|
|
48
|
+
? ''
|
|
49
|
+
: `Architecture role: ${escapeMarkdownText(metadata.architecture.role)}`,
|
|
50
|
+
renderList('Architectural invariants', metadata.architecture?.invariants),
|
|
51
|
+
]
|
|
52
|
+
.filter((value) => value !== '')
|
|
53
|
+
.join('\n\n');
|
|
54
|
+
return `## Repository
|
|
55
|
+
|
|
56
|
+
${repositoryDetails}
|
|
57
|
+
|
|
58
|
+
## Scope and boundaries
|
|
59
|
+
|
|
60
|
+
${scopeDetails || 'No additional scope or architecture facts are declared.'}
|
|
61
|
+
|
|
62
|
+
`;
|
|
63
|
+
}
|
|
64
|
+
/*** Render one optional authored collection as a deterministic Markdown list. */
|
|
65
|
+
function renderList(title, values) {
|
|
66
|
+
if (values === undefined || values.length === 0)
|
|
67
|
+
return '';
|
|
68
|
+
return `${title}:
|
|
69
|
+
|
|
70
|
+
${values.map((value) => `- ${escapeMarkdownText(value)}`).join('\n')}`;
|
|
71
|
+
}
|
|
72
|
+
/*** Escape inline-code delimiters and backslashes inside a managed Markdown code span. */
|
|
73
|
+
function escapeInlineCode(value) {
|
|
74
|
+
return normalizeText(value).replaceAll('\\', '\\\\').replaceAll('`', '\\`');
|
|
75
|
+
}
|
|
76
|
+
/*** Flatten authored prose and escape Markdown control characters before interpolation. */
|
|
77
|
+
function escapeMarkdownText(value) {
|
|
78
|
+
return [...normalizeText(value)]
|
|
79
|
+
.map((character) => (MARKDOWN_CONTROL_CHARACTERS.has(character) ? `\\${character}` : character))
|
|
80
|
+
.join('');
|
|
81
|
+
}
|
|
82
|
+
/*** Normalize authored prose to one managed Markdown line without changing its words. */
|
|
83
|
+
function normalizeText(value) {
|
|
84
|
+
return value.trim().replaceAll(/\s+/gu, ' ');
|
|
85
|
+
}
|
|
86
|
+
const MARKDOWN_CONTROL_CHARACTERS = new Set(['\\', '`', '*', '_', '[', ']', '<', '>']);
|
|
@@ -78,6 +78,14 @@ jobs:
|
|
|
78
78
|
echo "No build script found; skipping."
|
|
79
79
|
fi
|
|
80
80
|
|
|
81
|
+
- name: Validate owner-defined packed consumer
|
|
82
|
+
run: |
|
|
83
|
+
if node -e "const p=require('./package.json'); process.exit(p.scripts?.['test:packed-consumer'] ? 0 : 1)"; then
|
|
84
|
+
bun run test:packed-consumer
|
|
85
|
+
else
|
|
86
|
+
echo "No packed consumer test declared; skipping."
|
|
87
|
+
fi
|
|
88
|
+
|
|
81
89
|
- name: Verify npm release baseline
|
|
82
90
|
id: release-baseline
|
|
83
91
|
if: hashFiles('.changeset/config.json') != ''
|
|
@@ -227,19 +235,24 @@ jobs:
|
|
|
227
235
|
exit 1
|
|
228
236
|
fi
|
|
229
237
|
|
|
230
|
-
if [
|
|
238
|
+
if [ "$HIGHEST_PUBLISHED_VERSION" != "$current_version" ]; then
|
|
239
|
+
release_sha="$(git rev-parse HEAD)"
|
|
240
|
+
echo "Completing unpublished ${release_tag} from current main ${release_sha} without another version bump."
|
|
241
|
+
elif [ -n "$tagged_sha" ]; then
|
|
231
242
|
echo "Release tag ${release_tag} already points to ${release_sha}; resuming idempotent finalization."
|
|
232
243
|
else
|
|
233
244
|
echo "Recovering canonical release commit $release_sha for version $current_version without another version bump."
|
|
234
245
|
fi
|
|
235
246
|
|
|
236
|
-
if ! git diff --quiet || ! git diff --cached --quiet || [ -n "$(git ls-files --others --exclude-standard)" ]; then
|
|
247
|
+
if [ "$HIGHEST_PUBLISHED_VERSION" = "$current_version" ] && (! git diff --quiet || ! git diff --cached --quiet || [ -n "$(git ls-files --others --exclude-standard)" ]); then
|
|
237
248
|
git status --short
|
|
238
249
|
echo "::error title=Release recovery requires a clean worktree::A release preparation step modified the checkout before recovery. Refusing to discard changes while switching to canonical release commit $release_sha."
|
|
239
250
|
exit 1
|
|
240
251
|
fi
|
|
241
252
|
|
|
242
|
-
|
|
253
|
+
if [ "$HIGHEST_PUBLISHED_VERSION" = "$current_version" ]; then
|
|
254
|
+
git checkout --detach "$release_sha"
|
|
255
|
+
fi
|
|
243
256
|
echo "versioned=true" >> "$GITHUB_OUTPUT"
|
|
244
257
|
echo "package_name=$(node -p "require('./package.json').name")" >> "$GITHUB_OUTPUT"
|
|
245
258
|
echo "package_version=$current_version" >> "$GITHUB_OUTPUT"
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@ankhorage/devtools",
|
|
3
|
-
"version": "2.
|
|
3
|
+
"version": "2.8.1",
|
|
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",
|
|
@@ -526,16 +526,16 @@
|
|
|
526
526
|
},
|
|
527
527
|
"dependencies": {
|
|
528
528
|
"@ankhorage/apm": "^0.8.15",
|
|
529
|
-
"@ankhorage/capability": "^0.2.
|
|
530
|
-
"@ankhorage/contracts": "^26.11.
|
|
531
|
-
"@ankhorage/project-detector": "^0.3.
|
|
532
|
-
"@ankhorage/rules-repository": "^0.4.
|
|
529
|
+
"@ankhorage/capability": "^0.2.3",
|
|
530
|
+
"@ankhorage/contracts": "^26.11.1",
|
|
531
|
+
"@ankhorage/project-detector": "^0.3.6",
|
|
532
|
+
"@ankhorage/rules-repository": "^0.4.1",
|
|
533
533
|
"@ankhorage/utility": "^0.5.5",
|
|
534
534
|
"@changesets/cli": "^3.0.3",
|
|
535
535
|
"@eslint/compat": "^2.1.1",
|
|
536
536
|
"@eslint/js": "^10.0.1",
|
|
537
|
-
"@next/eslint-plugin-next": "^16.4.
|
|
538
|
-
"eslint": "^10.
|
|
537
|
+
"@next/eslint-plugin-next": "^16.4.6",
|
|
538
|
+
"eslint": "^10.15.0",
|
|
539
539
|
"eslint-config-prettier": "^10.1.8",
|
|
540
540
|
"eslint-plugin-import": "^2.32.0",
|
|
541
541
|
"eslint-plugin-prettier": "^5.5.7",
|
|
@@ -545,15 +545,15 @@
|
|
|
545
545
|
"eslint-plugin-security": "^4.2.1",
|
|
546
546
|
"eslint-plugin-simple-import-sort": "^14.0.0",
|
|
547
547
|
"eslint-plugin-unused-imports": "^4.4.1",
|
|
548
|
-
"knip": "^6.
|
|
549
|
-
"prettier": "^3.
|
|
548
|
+
"knip": "^6.45.1",
|
|
549
|
+
"prettier": "^3.10.1",
|
|
550
550
|
"typescript": "~6.0.3",
|
|
551
|
-
"typescript-eslint": "^8.72.
|
|
551
|
+
"typescript-eslint": "^8.72.2"
|
|
552
552
|
},
|
|
553
553
|
"devDependencies": {
|
|
554
|
-
"@ankhorage/paradox": "^0.
|
|
555
|
-
"@ankhorage/ankh": "^0.13.
|
|
556
|
-
"@ankhorage/doctor": "0.14.
|
|
554
|
+
"@ankhorage/paradox": "^0.5.0",
|
|
555
|
+
"@ankhorage/ankh": "^0.13.7",
|
|
556
|
+
"@ankhorage/doctor": "0.14.36",
|
|
557
557
|
"@techstark/opencv-js": "^5.0.0-release.1",
|
|
558
558
|
"@types/bun": "^1.4.2",
|
|
559
559
|
"@types/node": "^26.6.6",
|