chore: improve ci workflow, ensure built parser committed, cleanup (#166)

* chore: create npm build run-script
* chore: update npm test to include linting
* chore: add DEVELOPMENT.md
* chore: update README.md
* chore(workflow): check for uncommited changes
* chore: commit build diff (license header & new-lines)
* fix(workflow): setup-node's node-version arg

Author: erisu

.github/workflows/ci.yml

@@ -80,15 +80,36 @@ jobs:
 
       - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
         with:
-          node.version: ${{ matrix.node.version }}
+          node-version: ${{ matrix.node.version }}
 
       - name: Environment Information
         run: |
           node --version
           npm --version
 
-      - name: npm install and test
-        run: npm cit
+      - name: npm install
+        run: npm ci
+        env:
+          CI: true
+          NODE_OPTIONS: ${{ matrix.node.options }}
+
+      - name: Build parser
+        run: npm run build
+        env:
+          CI: true
+          NODE_OPTIONS: ${{ matrix.node.options }}
+
+      - name: Check for uncommitted changes
+        run: |
+          if ! git diff --exit-code; then
+            echo ""
+            echo "::error::Detected changes that appear to not be committed."
+            echo "::error::Please run 'npm run build' and commit the built parser."
+            exit 1
+          fi
+
+      - name: npm test
+        run: npm t
         env:
           CI: true
           NODE_OPTIONS: ${{ matrix.node.options }}

DEVELOPMENT.md

@@ -0,0 +1,105 @@
+<!--
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+-->
+
+# Development
+
+## Setup
+
+1. Install npm dependencies.
+
+    ```bash
+    npm install
+    ```
+
+## Updating the parser
+
+If there's a problem parsing, you will want to edit the grammar under `lib/parser/pbxproj.pegjs`.
+
+Tests under the `test/parser` directory will compile the parser from the grammar. The other tests will use the prebuilt parser (`lib/parser/pbxproj.js`).
+
+To build the parser js file after editing the grammar, run:
+
+```bash
+npm run build
+```
+
+## Unit Testing
+
+Our projects include unit tests, which can be run with:
+
+```bash
+npm test
+```
+
+## Linting
+
+During development, you should run the linter to ensure the code follows our coding standards:
+
+```bash
+npm run lint
+```
+
+> [!NOTE]
+> Running `npm test` will also execute the linter before running the tests.
+
+### Fixing Lint Issues
+
+In many cases, lint warnings can be fixed automatically with:
+
+```bash
+npm run lint:fix
+```
+
+If an issue cannot be resolved automatically, it will require manual review and correction.
+
+## Building from Source
+
+1. **Clone the repository** locally.
+
+2. **Change to the repository directory.**
+
+3. **Install dependencies:**
+
+    ```bash
+    npm install
+    ```
+
+    Installs all production and development dependencies required for using and developing the package.
+
+4. **Update sub-dependencies:**
+
+    ```bash
+    npm update
+    ```
+
+    Over time, `package-lock.json` can become stale and may trigger audit warnings. `npm update` refreshes dependencies within the pinned versions.
+
+    Under normal circumstances, users install the published package from the npm registry, which does **not** include its own `package-lock.json`. Instead, npm resolves and installs the latest compatible dependency versions at install time, which may result in no audit warnings.
+
+    Running `npm update` locally can provide a more accurate representation of current npm audit results for the project.
+
+5. **Generate a tarball:**
+
+    ```bash
+    npm pack
+    ```
+
+    Creates a `.tgz` tarball file in the `.asf-release` directory.

Makefile

@@ -37,39 +37,23 @@ based on donated code from [alunny / node-xcode](https://github.com/alunny/node-
 ## Example
 
 ```js
-// API is a bit wonky right now
-var xcode = require('xcode'),
-    fs = require('fs'),
-    projectPath = 'myproject.xcodeproj/project.pbxproj',
-    myProj = xcode.project(projectPath);
+const fs = require('node:fs');
+const xcode = require('xcode');
 
-// parsing is async, in a different process
+// Path to the Xcode project's project.pbxproj file.
+const projectPath = 'myproject.xcodeproj/project.pbxproj';
+// Create a PBXProject instance for the project.
+const myProj = xcode.project(projectPath);
+
+// Parse the project file asynchronously before making changes.
 myProj.parse(function (err) {
     myProj.addHeaderFile('foo.h');
     myProj.addSourceFile('foo.m');
     myProj.addFramework('FooKit.framework');
 
+    // Write the updated project back to disk.
     fs.writeFileSync(projectPath, myProj.writeSync());
-    console.log('new project written');
+
+    console.log('New project written');
 });
 ```
-
-## Working on the parser
-
-If there's a problem parsing, you will want to edit the grammar under
-`lib/parser/pbxproj.pegjs`. You can test it online with the PEGjs online thingy
-at https://pegjs.org/online - I have had some mixed results though.
-
-Tests under the `test/parser` directory will compile the parser from the
-grammar. Other tests will use the prebuilt parser (`lib/parser/pbxproj.js`).
-
-To rebuild the parser js file after editing the grammar, run:
-
-    npm run pegjs
-
-(and be sure to restore the Apache license notice in
-`lib/parser/pbxproj.js` before committing)
-
-## License
-
-Apache V2

README.md

@@ -0,0 +1,60 @@
+/*
+    Licensed to the Apache Software Foundation (ASF) under one
+    or more contributor license agreements.  See the NOTICE file
+    distributed with this work for additional information
+    regarding copyright ownership.  The ASF licenses this file
+    to you under the Apache License, Version 2.0 (the
+    "License"); you may not use this file except in compliance
+    with the License.  You may obtain a copy of the License at
+
+        http://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing,
+    software distributed under the License is distributed on an
+    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+    KIND, either express or implied.  See the License for the
+    specific language governing permissions and limitations
+    under the License.
+*/
+
+const fs = require('node:fs');
+const path = require('node:path');
+const peg = require('pegjs');
+
+const ROOT_DIR = path.join(__dirname, '..');
+const parserDir = path.join(ROOT_DIR, 'lib/parser');
+
+// Path to grammar file
+const grammarFilePath = path.join(parserDir, 'pbxproj.pegjs');
+// Path to where the parser file is outputted
+const outputFilePath = path.join(parserDir, 'pbxproj.js');
+
+// Fetches the grammar file content and builds the output data.
+const grammarData = fs.readFileSync(grammarFilePath, 'utf8');
+const outputData = peg.generate(grammarData, {
+    output: 'source',
+    format: 'commonjs'
+});
+
+const asfLicenseHeader = `/*
+    Licensed to the Apache Software Foundation (ASF) under one
+    or more contributor license agreements.  See the NOTICE file
+    distributed with this work for additional information
+    regarding copyright ownership.  The ASF licenses this file
+    to you under the Apache License, Version 2.0 (the
+    "License"); you may not use this file except in compliance
+    with the License.  You may obtain a copy of the License at
+
+        http://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing,
+    software distributed under the License is distributed on an
+    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+    KIND, either express or implied.  See the License for the
+    specific language governing permissions and limitations
+    under the License.
+*/
+`;
+
+// Append the Apache license header to the top of the built file.
+fs.writeFileSync(outputFilePath, `${asfLicenseHeader}${outputData}`);

bin/generate-pbxproj-parser.js

@@ -1,4 +1,4 @@
-/**
+/*
     Licensed to the Apache Software Foundation (ASF) under one
     or more contributor license agreements.  See the NOTICE file
     distributed with this work for additional information
@@ -16,7 +16,6 @@
     specific language governing permissions and limitations
     under the License.
 */
-
 /*
  * Generated by PEG.js 0.10.0.
  *

lib/parser/pbxproj.js

@@ -17,10 +17,10 @@
     "pegjs": "^0.10.0"
   },
   "scripts": {
-    "pegjs": "node_modules/.bin/pegjs lib/parser/pbxproj.pegjs",
+    "build": "node bin/generate-pbxproj-parser.js",
     "lint": "eslint .",
     "lint:fix": "npm run lint -- --fix",
-    "test": "node --test --experimental-test-coverage --test-reporter=spec --test-reporter=lcov --test-reporter-destination=stdout --test-reporter-destination=lcov.info"
+    "test": "npm run lint && node --test --experimental-test-coverage --test-reporter=spec --test-reporter=lcov --test-reporter-destination=stdout --test-reporter-destination=lcov.info"
   },
   "license": "Apache-2.0"
 }