name: Update ADEV Angular CDK apis

on:

workflow_dispatch:

inputs: {}

push:

branches:

- 'main'

- '[0-9]+.[0-9]+.x'

permissions:

contents: read

jobs:

update_cli_help:

name: Update Angular CDK apis (if necessary)

if: github.repository == 'angular/angular'

runs-on: ubuntu-latest

steps:

- name: Checkout the repository

uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2

with:

# Setting `persist-credentials: false` prevents the github-action account from being the

# account that is attempted to be used for authentication, instead the remote is set to

# an authenticated URL.

persist-credentials: false

# This is needed as otherwise the PR creation will fail with `shallow update not allowed` when the forked branch is not in sync.

fetch-depth: 0

- name: Generate CDK apis

run: node adev/scripts/update-cdk-apis/index.mjs

env:

ANGULAR_CDK_BUILDS_READONLY_GITHUB_TOKEN: ${{ secrets.ANGULAR_CDK_BUILDS_READONLY_GITHUB_TOKEN }}

- name: Create a PR (if necessary)

uses: angular/dev-infra/github-actions/create-pr-for-changes@14c3d6bd2fa5c3231be7bd4b3c0bba68c9d79e94

with:

branch-prefix: update-cdk-apis

pr-title: 'docs: update Angular CDK apis [${{github.ref_name}}]'

pr-description: |

pr-labels: |

angular-robot-token: ${{ secrets.ANGULAR_ROBOT_ACCESS_TOKEN }}

import {execSync} from 'node:child_process';

import {existsSync, constants as fsConstants} from 'node:fs';

import {copyFile, mkdtemp, readdir, readFile, realpath, unlink, writeFile} from 'node:fs/promises';

import {tmpdir} from 'node:os';

import {join} from 'node:path';

export async function copyJsonAssets({repo, githubApi, assetsPath, destPath}) {

const buildInfoPath = join(destPath, '_build-info.json');

if (!existsSync(buildInfoPath)) {

throw new Error(`${buildInfoPath} does not exist.`);

}

const branch = process.env.GITHUB_REF;

const {sha: currentSha} = JSON.parse(await readFile(buildInfoPath, 'utf-8'));

const latestSha = await githubApi.getShaForBranch(branch);

console.log(`Comparing ${currentSha}...${latestSha}.`);

const affectedFiles = await githubApi.getAffectedFiles(currentSha, latestSha);

const changedFiles = affectedFiles.filter((file) => file.startsWith(`${assetsPath}/`));

if (changedFiles.length === 0) {

console.log(`No '${assetsPath}/**' files changed between ${currentSha} and ${latestSha}.`);

return;

}

console.log(

`The below files changed between ${currentSha} and ${latestSha}:\n` +

changedFiles.map((f) => '* ' + f).join('\n'),

);

const temporaryDir = await realpath(await mkdtemp(join(tmpdir(), 'copy-json-assets-')));

const execOptions = {cwd: temporaryDir, stdio: 'inherit'};

execSync('git init', execOptions);

execSync(`git remote add origen https://github.com/${repo}.git`, execOptions);

// fetch a commit

execSync(`git fetch origen ${latestSha}`, execOptions);

// reset this repository's main branch to the commit of interest

execSync('git reset --hard FETCH_HEAD', execOptions);

// get sha when files where changed

const shaWhenFilesChanged = execSync(`git rev-list -1 ${latestSha} "${assetsPath}/"`, {

encoding: 'utf8',

cwd: temporaryDir,

stdio: ['ignore', 'pipe', 'ignore'],

}).trim();

// Delete existing asset files.

const apiFilesUnlink = (await readdir(destPath))

.filter((f) => f.endsWith('.json'))

.map((f) => unlink(join(destPath, f)));

await Promise.allSettled(apiFilesUnlink);

// Copy new asset files

const tempAssetsDir = join(temporaryDir, assetsPath);

const assetFilesCopy = (await readdir(tempAssetsDir)).map((f) => {

const src = join(tempAssetsDir, f);

const dest = join(destPath, f);

return copyFile(src, dest, fsConstants.COPYFILE_FICLONE);

});

await Promise.allSettled(assetFilesCopy);

// Write SHA to file.

await writeFile(

buildInfoPath,

JSON.stringify(

{

branchName: branch,

sha: shaWhenFilesChanged,

},

undefined,

2,

),

);

console.log('\nChanges: ');

execSync(`git status --porcelain`, {stdio: 'inherit'});

console.log(`Successfully updated asset files in '${destPath}'.\n`);

import {get} from 'node:https';

import {posix} from 'node:path';

const GITHUB_API = 'https://api.github.com/repos/';

export class GithubClient {

#token;

#ua;

#api;

constructor(repo, token, ua) {

this.#token = token;

this.#ua = ua;

this.#api = posix.join(GITHUB_API, repo);

}

/**

async getAffectedFiles(baseSha, headSha) {

const {files} = JSON.parse(await this.#httpGet(`${this.#api}/compare/${baseSha}...${headSha}`));

return files.map((f) => f.filename);

}

/**

async getShaForBranch(branch) {

const sha = await this.#httpGet(`${this.#api}/commits/${branch}`, {

headers: {Accept: 'application/vnd.github.VERSION.sha'},

});

if (!sha) {

throw new Error(`Unable to extract the SHA for '${branch}'.`);

}

return sha;

}

#httpGet(url, options = {}) {

options.headers ??= {};

options.headers['Authorization'] = `token ${this.#token}`;

// User agent is required

// https://docs.github.com/en/rest/overview/resources-in-the-rest-api?apiVersion=2022-11-28#user-agent-required

options.headers['User-Agent'] = this.#ua;

return new Promise((resolve, reject) => {

get(url, options, (res) => {

let data = '';

res

.on('data', (chunk) => {

data += chunk;

})

.on('end', () => {

resolve(data);

});

}).on('error', (e) => {

reject(e);

});

});

}

This script updates the Angular CDK api JSON files stored in `adev/src/content/cdk`. This files are used to generate the [angular.dev api](https://angular.dev/api) pages for the CDK packages.

import {dirname, resolve as resolvePath} from 'node:path';

import {fileURLToPath} from 'node:url';

import {copyJsonAssets} from '../shared/copy-json-assets.mjs';

import {GithubClient} from '../shared/github-client.mjs';

const scriptDir = dirname(fileURLToPath(import.meta.url));

const CDK_BUILDS_REPO = 'angular/cdk-builds';

const CDK_APIS_CONTENT_PATH = resolvePath(scriptDir, '../../src/content/cdk');

async function main() {

await copyJsonAssets({

repo: CDK_BUILDS_REPO,

assetsPath: '_adev_assets',

destPath: CDK_APIS_CONTENT_PATH,

githubApi: new GithubClient(

CDK_BUILDS_REPO,

process.env.ANGULAR_CDK_BUILDS_READONLY_GITHUB_TOKEN,

'ADEV_Angular_CDK_Sources_Update',

),

});

main().catch((err) => {

console.error(err);

process.exit(1);