@ankhorage/devtools 2.7.0 → 2.8.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
@@ -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
- # @ankhorage/devtools
4
+ # Ankhorage Devtools
5
5
 
6
- ![license: MIT](././paradox/badges/license.svg) ![npm: v2.7.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)
6
+ ![license: MIT](././paradox/badges/license.svg) ![npm: v2.8.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
- Shared tooling, repository automation, and agent standards for Ankhorage TypeScript projects
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
- ## Generated documentation
40
+ ## Documentation
39
41
 
40
- - [Interactive documentation app](././paradox/index.html)
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, REPOSITORY_RULE_METADATA, } from '@ankhorage/rules-repository';
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 readMetadataFactAsync(targetDirectory);
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 readMetadataFactAsync(targetDirectory);
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
- export declare function getReadmeDocumentationErrors(readmeContents: string): string[];
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
- '## Generated documentation',
7
+ '## Documentation',
9
8
  'paradox/index.html',
10
9
  ];
11
- export function getReadmeDocumentationErrors(readmeContents) {
12
- return REQUIRED_README_SNIPPETS.flatMap((snippet) => readmeContents.includes(snippet)
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
- ## Repository
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(['\\', '`', '*', '_', '[', ']', '<', '>']);
@@ -227,19 +227,24 @@ jobs:
227
227
  exit 1
228
228
  fi
229
229
 
230
- if [ -n "$tagged_sha" ]; then
230
+ if [ "$HIGHEST_PUBLISHED_VERSION" != "$current_version" ]; then
231
+ release_sha="$(git rev-parse HEAD)"
232
+ echo "Completing unpublished ${release_tag} from current main ${release_sha} without another version bump."
233
+ elif [ -n "$tagged_sha" ]; then
231
234
  echo "Release tag ${release_tag} already points to ${release_sha}; resuming idempotent finalization."
232
235
  else
233
236
  echo "Recovering canonical release commit $release_sha for version $current_version without another version bump."
234
237
  fi
235
238
 
236
- if ! git diff --quiet || ! git diff --cached --quiet || [ -n "$(git ls-files --others --exclude-standard)" ]; then
239
+ if [ "$HIGHEST_PUBLISHED_VERSION" = "$current_version" ] && (! git diff --quiet || ! git diff --cached --quiet || [ -n "$(git ls-files --others --exclude-standard)" ]); then
237
240
  git status --short
238
241
  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
242
  exit 1
240
243
  fi
241
244
 
242
- git checkout --detach "$release_sha"
245
+ if [ "$HIGHEST_PUBLISHED_VERSION" = "$current_version" ]; then
246
+ git checkout --detach "$release_sha"
247
+ fi
243
248
  echo "versioned=true" >> "$GITHUB_OUTPUT"
244
249
  echo "package_name=$(node -p "require('./package.json').name")" >> "$GITHUB_OUTPUT"
245
250
  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.7.0",
3
+ "version": "2.8.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",
@@ -526,16 +526,16 @@
526
526
  },
527
527
  "dependencies": {
528
528
  "@ankhorage/apm": "^0.8.15",
529
- "@ankhorage/capability": "^0.2.2",
530
- "@ankhorage/contracts": "^26.11.0",
531
- "@ankhorage/project-detector": "^0.3.5",
532
- "@ankhorage/rules-repository": "^0.4.0",
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.5",
538
- "eslint": "^10.14.0",
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.44.1",
549
- "prettier": "^3.9.10",
548
+ "knip": "^6.45.1",
549
+ "prettier": "^3.10.1",
550
550
  "typescript": "~6.0.3",
551
- "typescript-eslint": "^8.72.1"
551
+ "typescript-eslint": "^8.72.2"
552
552
  },
553
553
  "devDependencies": {
554
- "@ankhorage/paradox": "^0.3.6",
555
- "@ankhorage/ankh": "^0.13.5",
556
- "@ankhorage/doctor": "0.14.35",
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",