[Chores] Automated API doc generation and added packages/samples filt…

…er (#1470)

* Update configuration

* Test API doc generation and samples linting

* Revert changes

* Update

* Test changes for API doc

* Update script

* Update

* Update

* Test linting

* Update script

* Update API docs [skip ci]

* Update [skip ci]

* Revert "Update API docs [skip ci]"

This reverts commit 458c93f.

* Apply [skip ci]

* Update comments [skip ci]

* Revert changes

* Revert [skip ci]

* Add comment [skip ci]

* Update path

* update CHANGELOG

* test

* Update according to review

---------

Co-authored-by: Automated Build <builds@sitecore.com>

CHANGELOG.md

@@ -32,6 +32,7 @@ Our versioning strategy is as follows:
 
 ### 🧹 Chores
 
+* Automated API doc generation and added packages/samples filter ([#1470](https://github.com/Sitecore/jss/pull/1470))
 * Revisit and update github ISSUE_TEMPLATE ([#1445](https://github.com/Sitecore/jss/pull/1445))
 * Configure the recommended VSCode extensions for the starters ([#1437](https://github.com/Sitecore/jss/pull/1437))
 * `[templates/nextjs]` `[templates/nextjs-styleguide-tracking]` Move remaining Styleguide-Tracking artifacts from the base template ([#1422](https://github.com/Sitecore/jss/pull/1422))

azure-pipelines.yml

@@ -87,34 +87,49 @@ steps:
   displayName: 'lint samples'
   condition: and(succeeded(), ne(variables.shouldPublish, true))
 
-  #
-  # LERNA VERSION
   # * Configure git with a commit user
   # * Update git remote to include a Personal Access Token, so lerna can push
   # * Explicitly check out the current branch since Pipelines will use disconnected HEAD by default
-  # * Increment pre-release version
-  #     * Force version update even if lerna doesn't detect changes
-  #     * Include [skip ci] in commit message to stop pipeline from triggering again when lerna pushes
-  # * Only run for 'dev' branch
-  #
+  # * Only run for 'dev' and 'release' branches
 - script: |
     git config user.email builds@sitecore.com
     git config user.name "Automated Build"
     git remote set-url origin https://$GITHUB_PAT_ENV@github.com/Sitecore/jss.git
     git checkout $(branchName)
+  displayName: 'apply git configuration'
+  condition: and(succeeded(), eq(variables.shouldPublish, true))
+  env:
+    GITHUB_PAT_ENV: $(GITHUB-PAT)
+
+  # Only run for 'dev' and 'release' branches
+  # in order to don't produce extra changes in the Pull Request
+- script: |
+    yarn generate-docs
+    git add ./ref-docs/**/*
+    git commit -m "Update API docs [skip ci]"
+  displayName: 'generate API docs'
+  condition: and(succeeded(), eq(variables.shouldPublish, true))
+
+  #
+  # LERNA VERSION
+  # * Increment pre-release version
+  #     * Force version update even if lerna doesn't detect changes
+  #     * Include [skip ci] in commit message to stop pipeline from triggering again when lerna pushes
+  # * Only run for 'dev' and 'release' branches
+  #
+- script: |
     $(npm bin)/lerna version prerelease --preid canary --force-publish --message "version %s [skip ci]" --yes
   displayName: 'pre-release version update'
   condition: and(succeeded(), eq(variables.shouldPublish, true))
   env:
-    GITHUB_PAT_ENV: $(GITHUB-PAT)
     YARN_ENABLE_IMMUTABLE_INSTALLS: false
   #
   # LERNA PUBLISH
   # * Configure npm to use the provided access token, so lerna can publish
   # * Do a lerna canary publish of the version we've already updated and pushed
   # * Disable access verification (no-verify-access) as this doesn't seem to work behind Azure DevOps' npm proxy
   #     * https://github.com/lerna/lerna/issues/1685
-  # * Only run for 'dev' branch
+  # * Only run for 'dev' and 'release' branches
   #
 - script: |
     echo //registry.npmjs.org/:_authToken=${NPM_TOKEN} > .npmrc

package.json

@@ -3,13 +3,13 @@
   "scripts": {
     "reset": "lerna clean --yes && yarn dlx rimraf node_modules && yarn install && yarn build",
     "build": "lerna run build",
-    "lint-packages": "lerna run lint",
-    "lint-samples": "lerna run lint --scope 'sample-*' -- --fix",
+    "lint-packages": "lerna run lint --since=origin/dev",
     "scaffold-samples": "node ./scripts/scaffold-samples.js",
+    "lint-samples": "node ./scripts/lint-samples.js",
     "coverage-packages": "lerna run coverage",
     "test-packages": "lerna run test",
     "install-git-hooks": "node ./scripts/install-hooks.js",
-    "generate-docs": "lerna run generate-docs",
+    "generate-docs": "lerna run generate-docs --since=origin/dev",
     "version": "yarn install && git stage yarn.lock"
   },
   "author": {

scripts/lint-samples.js

@@ -0,0 +1,45 @@
+const { execSync } = require('child_process');
+const samples = require('./samples.json');
+const { getAppName } = require('./utils');
+
+/**
+ * Start linting process only for the samples that were affected by the new changes in:
+ * - create-sitecore-jss/src/templates/**
+ * - create-sitecore-jss/src/initializers/**
+ */
+
+const affectedTemplates = execSync(
+  'git diff --name-only origin/dev... -- packages/create-sitecore-jss',
+  {
+    encoding: 'utf-8',
+  }
+)
+  .split('\n')
+  .map((filepath) => {
+    // Extracting template names from the filepath
+    const template = filepath.match(/(templates|initializers)\/([^\/]*)/);
+
+    return template && template[2];
+  })
+  // Removing null values and leaving unique template names
+  .filter((template, index, list) => template && list.indexOf(template) === index);
+
+if (!affectedTemplates.length) {
+  console.log('No modified templates to lint');
+
+  return;
+}
+
+const affectedSamples = samples
+  .filter((sample) => sample.initializers.some((template) => affectedTemplates.includes(template)))
+  .map((sample) => getAppName(sample.args));
+
+if (!affectedSamples.length) {
+  console.log('No modified samples to lint');
+
+  return;
+}
+
+execSync(`npx lerna run lint --scope={${affectedSamples.join(',')}} -- --fix`, {
+  stdio: 'inherit',
+});

scripts/scaffold-samples.js

@@ -2,9 +2,10 @@ const chalk = require('chalk');
 
 const { initRunner } = require('../packages/create-sitecore-jss/dist/init-runner');
 const samplesToScaffold = require('./samples.json');
+const { getAppName } = require('./utils');
 
 for (const sample of samplesToScaffold) {
-  sample.args.appName = `sample-${sample.args.appName}-${sample.args.fetchWith || ''}-${sample.args.prerender || ''}`;
+  sample.args.appName = getAppName(sample.args);
   sample.args.destination = `./samples/${sample.args.appName}`;
   sample.args.hostName = `${sample.args.appName}.jss.localhost`;
   console.log(chalk.green(`Initializing sample ${sample.args.appName} ...`));
@@ -17,6 +18,6 @@ for (const sample of samplesToScaffold) {
     silent: true,
     noInstall: true,
     ...sample.args,
-  }
+  };
   initRunner(sample.initializers, scaffoldArgs);
-};
+}

scripts/utils.js

@@ -0,0 +1,7 @@
+/**
+ * Generates unique app name based on sample app configuration
+ * @param {Record<string, string>} args sample app arguments
+ * @returns unique app name
+ */
+module.exports.getAppName = (args) =>
+  `sample-${args.appName}-${args.fetchWith || ''}-${args.prerender || ''}`;