diff --git a/aio/tools/transforms/examples-package/processors/check-for-unused-example-regions.js b/aio/tools/transforms/examples-package/processors/check-for-unused-example-regions.js new file mode 100644 index 0000000000..f94b4d78c7 --- /dev/null +++ b/aio/tools/transforms/examples-package/processors/check-for-unused-example-regions.js @@ -0,0 +1,38 @@ +/** + * @license + * Copyright Google LLC All Rights Reserved. + * + * Use of this source code is governed by an MIT-style license that can be + * found in the LICENSE file at https://angular.io/license + */ + +/** + * A processor that will fail if there are named example regions that are not used in any docs. + * + * @param {*} exampleMap - contains all the regions extracted from example files. + */ +module.exports = function checkForUnusedExampleRegions(exampleMap) { + return { + $runAfter: ['renderExamples'], + $runBefore: ['writing-files'], + $process() { + const unusedExampleRegions = []; + for (const exampleFolder of Object.values(exampleMap)) { + for (const exampleFile of Object.values(exampleFolder)) { + for (const [regionName, region] of Object.entries(exampleFile.regions)) { + if (regionName === '' || region.usedInDoc) continue; + unusedExampleRegions.push(region); + } + } + } + + if (unusedExampleRegions.length > 0) { + const message = (unusedExampleRegions.length === 1 ? + 'There is 1 unused example region:\n' : + `There are ${unusedExampleRegions.length} unused example regions:\n`) + + unusedExampleRegions.map(region => ` - ${region.id}`).join('\n'); + throw new Error(message); + } + }, + }; +}; diff --git a/aio/tools/transforms/examples-package/processors/check-for-unused-example-regions.spec.js b/aio/tools/transforms/examples-package/processors/check-for-unused-example-regions.spec.js new file mode 100644 index 0000000000..56021e38b2 --- /dev/null +++ b/aio/tools/transforms/examples-package/processors/check-for-unused-example-regions.spec.js @@ -0,0 +1,77 @@ +/** + * @license + * Copyright Google LLC All Rights Reserved. + * + * Use of this source code is governed by an MIT-style license that can be + * found in the LICENSE file at https://angular.io/license + */ +const testPackage = require('../../helpers/test-package'); +const Dgeni = require('dgeni'); + +describe('checkForUnusedExampleRegions', () => { + var processor, exampleMap; + + beforeEach(function() { + const dgeni = new Dgeni([testPackage('examples-package', true)]); + const injector = dgeni.configureInjector(); + exampleMap = injector.get('exampleMap'); + processor = injector.get('checkForUnusedExampleRegions'); + }); + + describe('$process()', () => { + it('should error if there is a named example region which has not been used', () => { + exampleMap['examples'] = { + 'some/file': { + regions: { + '': {id: 'some/file#'}, + 'used': {id: 'some/file#used', usedInDoc: {}}, + 'not-used': {id: 'some/file#not-used'}, + } + } + }; + expect(() => processor.$process()) + .toThrowError('There is 1 unused example region:\n - some/file#not-used'); + }); + + it('should not error if there are no example folders', () => { + expect(() => processor.$process()).not.toThrowError(); + }); + + it('should not error if there are no example files', () => { + exampleMap['examples'] = {}; + expect(() => processor.$process()).not.toThrowError(); + }); + + it('should not error if there are no example regions', () => { + exampleMap['examples'] = { + 'some/file': { + regions: {}, + }, + }; + expect(() => processor.$process()).not.toThrowError(); + }); + + it('should not error if there are no named example regions', () => { + exampleMap['examples'] = { + 'some/file': { + regions: { + '': {id: 'some/file#'}, + }, + }, + }; + expect(() => processor.$process()).not.toThrowError(); + }); + + it('should not error if there are no unused named example regions', () => { + exampleMap['examples'] = { + 'some/file': { + regions: { + '': {id: 'some/file#'}, + 'used': {id: 'some/file#used', usedInDoc: {}}, + } + } + }; + expect(() => processor.$process()).not.toThrowError(); + }); + }); +});