Initial Documentation Content, Parsing Markdown Content Library, and …

…Package Publishing Scaffolding (#4)

* wip initial structure

* add logo

* rename sections to pages

* add Documentation class to parse contents

* handle h3 headings and below

* remove accidental console.log

* remove intro and add version to class

* add contributing guidelines

* Initial Documentation Publishing Setup (#3)

* add npm code linting dependencies, add github workflow files, add dependabot config

* set type module in package.json

* remove references to test script in quality workflow

* temporarily disable dist-tag commands

* comment back in dist-tag logic after publishing initial version of package

* remove jest reference in root-level package.json

* add .npmignore file to avoid publishing the repo's .github/ directory

* add marked as a dependency, and export parsed markdown files content from index file

* add build step to building workflow

* update documentation classes to execute async where possible, update build process on releases, minor directory path adjustments

* linting and various path reference adjustments

* hotfix section key value generation by reverting back to prior implimentation

* remove unneeded root-level files, rename src directory to lib

* add build script, dummy internal link in GettingStarted doc

* add sample mermaid diagram to getting started doc

* add complex mermaid example, hotfix link path in getting started doc

* resize logo

* updated GettingStarted

* hotfix path for logo.png

* add subsection class for prasing subsections from documentation files

* add consolidate parsing code, add test.md file with complex markdown examples

* address edge case situation to ensure all sections and subsections on a page are assigned unique key values

* adjust key value assignment logic when processing documentation files to ensure uniqueness/consistency

* tweak key assignment in documentation classes, general code cleanup and add code comments

* adjust anchor tag generation to mirror github's assignment pattern

* add title key generation for a page

* content wip

* add quickstart to pages array in lib/index.js, link markdown files

* rename key property to pageKey and titleKey to disambiguate key property within the frontend

* placeholder content to Test.md to examine how github renders the anchor tags

* test renaming test file to non-alphanumerical letter to examine how github presents file

* revert filename change of test file

* tweaks to better match githubs anchor tag id assignment behavior

* correct letter casing of Test.md file

* add addtional test markdown links to Test.md

* updated inital content

* updated index pages

* hotfix incorrect hash section references, adjust files listed in index.js to only reference files currently included in repo, remove Test markdown file

* bump marked to v4.1.1

* general dependency audit

* remove linking to documentation file that are currently not being provided to end users

Co-authored-by: Chloe Wintzer <[email protected]>

.github/dependabot.yml

@@ -0,0 +1,31 @@
+version: 2
+
+registries:
+  npm-github:
+    type: npm-registry
+    url: https://npm.pkg.github.com
+    token: ${{ secrets.PACKAGES_READ_TOKEN }}
+
+updates:
+  - package-ecosystem: 'github-actions'
+    directory: '/'
+    schedule:
+      interval: 'weekly'
+      day: 'monday'
+      time: '12:00'
+    labels:
+      - 'dependabot'
+    open-pull-requests-limit: 50
+
+  - package-ecosystem: 'npm'
+    directory: '/'
+    registries:
+      - npm-github
+    schedule:
+      interval: 'weekly'
+      day: 'monday'
+      time: '12:00'
+    labels:
+      - 'dependabot'
+    open-pull-requests-limit: 50
+    versioning-strategy: 'increase'

.github/workflows/build.js

@@ -0,0 +1,13 @@
+import { mkdir, writeFile } from 'node:fs/promises'
+import { fileURLToPath } from 'node:url'
+import documentation from '../../lib/index.js'
+
+const getFilePath = path => (
+  fileURLToPath(new URL(`../../${path}`, import.meta.url))
+)
+
+const distPath = getFilePath('dist')
+const jsonPath = getFilePath('dist/index.json')
+
+await mkdir(distPath, { recursive: true })
+await writeFile(jsonPath, JSON.stringify(documentation))

.github/workflows/bump.js

@@ -0,0 +1,80 @@
+import child from 'child_process'
+import { promisify } from 'util'
+import packageJson from '../../package.json' assert { type: 'json' }
+
+const exec = promisify(function (command, done) {
+  console.log(`Executing: '${command}'`)
+  child.exec(command, (error, stdout, stderr) => {
+    if (error) return done(error)
+    console.error(stderr)
+    console.log(stdout)
+    done(null, { stdout, stderr })
+  })
+})
+
+const getDistTags = async () => {
+  return Object.fromEntries(
+    (await exec(`npm dist-tag ${packageName}`))
+      .stdout
+      .split(/\r\n|\r|\n/)
+      .filter(Boolean)
+      .map(version => version.split(': '))
+  )
+}
+
+const packageName = packageJson.name
+const githubRef = process.env.GITHUB_REF
+if (!githubRef) throw new Error('Missing githubRef')
+
+// matches format '1.2.3'
+const latestMatch = /^refs\/tags\/v([0-9]+)\.([0-9]+)\.([0-9]+)$/
+// matches format '1.2.3-4'
+const nextMatch = /^refs\/tags\/v([0-9]+)\.([0-9]+)\.([0-9]+)\-([0-9]+)$/
+// matches format '1.2.3-alpha.4'
+const preMatch = /^refs\/tags\/v([0-9]+)\.([0-9]+)\.([0-9]+)\-[a-zA-Z0-9_]+\.([0-9]+)$/
+
+let distTag = ''
+if (latestMatch.test(githubRef)) {
+  distTag = 'latest'
+} else if (nextMatch.test(githubRef)) {
+  distTag = 'next'
+} else if (preMatch.test(githubRef)) {
+  // if version is '1.0.0-alpha.0', will assign distTag to 'alpha'
+  distTag = githubRef.replace(/(^refs\/tags\/v([0-9]+)\.([0-9]+)\.([0-9]+)\-|\.([0-9]+)$)/g, '')
+}
+// throw error if we cannot determine dist-tag 
+if (!distTag) throw new Error('Unable to determine dist-tag')
+
+const versionNumber = githubRef?.replace(/^refs\/tags\/v/, '')
+if (!versionNumber) throw new Error('Missing versionNumber')
+
+console.log(`Releasing version 'v${versionNumber}' to '${distTag}' channel`)
+
+// array of before dist-tags
+const targetTags = await getDistTags()
+
+// bump version, but do not create associated tag/commit
+await exec(`npm --no-git-tag-version version ${versionNumber}`)
+
+// build static documentation json file
+await exec(`node .github/workflows/build.js`)
+
+// publish version with parsed dist-tag
+await exec(`npm publish --tag ${distTag}`)
+
+// insert published version into target dist-tags object
+targetTags[distTag] = versionNumber
+
+const afterTags = await getDistTags()
+
+// reassign distTags
+for (const [tag, version] of Object.entries(targetTags)) {
+  if (afterTags[tag] !== version) {
+    await exec(`npm dist-tag add ${packageName}@${version} ${tag}`)
+  }
+}
+
+// remove erroneously assigned dist-tags
+for (const tag in afterTags) {
+  if (!(tag in targetTags)) await exec(`npm dist-tag rm ${packageName} ${tag}`)
+}

.github/workflows/publish.yml

@@ -0,0 +1,51 @@
+name: Build and Publish Package
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    name: Build and Publish
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: write
+      packages: write
+
+    timeout-minutes: 5
+    steps:
+      - name: Code Checkout
+        uses: actions/checkout@v3
+
+      - name: Install NodeJS
+        uses: actions/setup-node@v3
+        with:
+          node-version: 16
+          registry-url: 'https://npm.pkg.github.com'
+          scope: '@noop-inc'
+
+      - name: Cache NPM
+        id: cache-npm
+        uses: actions/cache@v3
+        with:
+          path: |
+            ~/.npm
+            ./node_modules
+          key: ${{ runner.os }}-npm-${{ hashFiles('package-lock.json') }}
+          restore-keys: ${{ runner.os }}-npm-
+
+      - name: Install Dependencies
+        if: steps.cache-npm.outputs.cache-hit != 'true'
+        run: npm ci
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.PACKAGES_READ_TOKEN }}
+
+      - name: Build Documentation JSON File
+        run: node .github/workflows/build.js
+
+      - name: Bump and Publish
+        run: node .github/workflows/bump.js
+        env:
+          GITHUB_REF: ${{ github.ref }}
+          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/quality.yml

@@ -0,0 +1,51 @@
+name: Code Quality
+
+on:
+  pull_request:
+    types: [opened, reopened, synchronize]
+  push:
+    branches: [main]
+
+jobs:
+  linting:
+    name: Linting
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - name: Code Checkout
+        uses: actions/checkout@v3
+
+      - name: Install NodeJS
+        uses: actions/setup-node@v3
+        with:
+          node-version: 16
+          registry-url: 'https://npm.pkg.github.com'
+          scope: '@noop-inc'
+
+      - name: Cache NPM
+        id: cache-npm
+        uses: actions/cache@v3
+        with:
+          path: |
+            ~/.npm
+            ./node_modules
+          key: ${{ runner.os }}-npm-${{ hashFiles('package-lock.json') }}
+          restore-keys: ${{ runner.os }}-npm-
+
+      - name: Install Dependencies
+        run: npm ci
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.PACKAGES_READ_TOKEN }}
+
+      - name: Cache Lint
+        id: cache-lint
+        uses: actions/cache@v3
+        with:
+          path: |
+            ./node_modules/.cache/prettier
+            ./node_modules/.cache/.eslintcache
+          key: ${{ runner.os }}-lint-${{ github.sha }}
+          restore-keys: ${{ runner.os }}-lint-
+
+      - name: Code Linting
+        run: npm run lint

.gitignore

@@ -0,0 +1,3 @@
+node_modules
+dist
+*.tgz

README.md

@@ -1,2 +1,14 @@
-# documentation
+# Noop Documentation
+
 Central Repository of Noop Documentation
+
+## Getting Started
+
+Jump in to the documentation now with [Getting Started](docs/GettingStarted.md)
+
+## Contributing
+
+This repository contains the authoratative content of Noop documenation. This content is authored in an intentionally minimalistic Markdown format so it can be rendered within a variety of clients. Our parser enforces two key concepts to the Markdown, particularly on the use of headers.
+
+- Each Markdown file in the `./docs/` directory is a **Page**. The title of the page is read from the first h1 block, like `# Page Title`. If there are other h1 blocks, they are disregared.
+- Each **Page** contains zero or more **Sections** which are demarcated by h2 blocks, like `## Section Title`. All the Markdown content that follows up until another h2 is included in the section body.

docs/Applications.md

@@ -0,0 +1,26 @@
+# Applications
+
+Applications are a representation of an entire system defined in a single software repository. They store [Builds](/docs/Builds.md) of the [Source Code](/docs/Builds.md#source-code) and can host several [Environments](/docs/Environments.md).
+
+## Linked Repositories
+
+Applications can be linked to a Repository to integrate with it's code and events automatically. Linked Resositories connect Source Code to Builds and power [Pipelines](/docs/Pipelines.md).
+
+## Noop Application Model
+
+Noop offers a broad set of [Components](/docs/Components.md), [Resources](/docs/Resources.md), and other options like [Routes](/docs/Traffic.md#routing-rules) to build your Application. You define your needs in your [AppManifest](/docs/Manifests.md#appmanifest) within your code. This means that your code completely describes itself as a system, not through the intermediate levels of containers or infrastructure.
+
+You can mix and match as many Components and Resources as you need in your Application as it grows and evolves. We strive to offer the least-opinionated building blocks possible for your to use when designing and constructing your code. Noop only has opinions to how you code when there aren't decent standards-based practices available and there is a compelling benefit to our users.
+
+```mermaid
+flowchart LR
+  subgraph Routes
+    Traffic
+  end
+  subgraph Components
+    Traffic-->ApiService
+  end
+  subgraph Resources
+    ApiService-->Customers
+  end
+```

docs/Builds.md

@@ -0,0 +1,39 @@
+# Builds
+
+A Build is an artifact of your [Component](/docs/Components.md) Source Code that has been processed through your own [Build Steps](#build-steps).
+
+## Build Steps
+
+You can define any compilation, packaging, or testing steps for your Components within the [AppManifest](/docs/Manifests.md#appmanifest).
+
+### Run Step
+
+Execute a command.
+
+```yaml
+steps:
+  - run: npm ci
+```
+
+### Copy Step
+
+Copy files from your source code into the current directory.
+
+```yaml
+steps:
+  - copy: package.json
+  - copy: *
+```
+
+### Directory Step
+
+Set the current working directory.
+
+```yaml
+steps:
+  - directory: /build
+```
+
+## Source Code
+
+Source Code represents a discreet version of your code that has been indexed and archived by Noop.

docs/Clusters.md

@@ -0,0 +1,7 @@
+# Clusters
+
+A Cluster is an instance of Noop infrastructure running in a designated region. They provide a high degree of isolation for compute and data.
+
+## Shared Clusters
+
+While in our private preview, we are only offering a few shared Clusters to be used by all participants.