add: project phase 2 spec and library

Author: arranstewart

assets/project/project-spec-2025-phase-2.md

@@ -0,0 +1,220 @@
+<!--
+Create pdf with
+pandoc project-spec-2025.md -s -o project-spec-2025.pdf
+See installation notes here
+https://gist.github.com/ilessing/7ff705de0f594510e463146762cef779
+-->
+
+---
+title: |
+  ```{=latex}
+  \vspace{-2em}CITS5501/CITS3501 Project 2025 phase 2
+  ```
+classoption:    oneside
+papersize:      a4
+fontsize:       12pt
+geometry:
+- top=0.9in
+- bottom=0.8in
+- left=0.7in
+- right=0.7in
+colorlinks:   true
+linkcolor: blue
+urlcolor: blue
+---
+
+\vspace{-3em}
+
+| **Version:** | 0.1                    |
+|--------------|------------------------|
+| **Date:**    | 12 September 2025      |
+
+<!--
+**Changes in version 0.2**
+
+- Changes here
+- Changes here
+-->
+
+
+<!-- these abbreviations only work in pdf not in html -->
+\def\travelsystem{\textsc{Tachi}} <!-- (https://en.wikipedia.org/wiki/Tachi) -->
+\def\travelco{\textsc{Koto}} <!-- Tachi were the mainstream Japanese swords of the Kotō period between 900 and 1596 -->
+\def\iata{\textsc{iata}}
+\def\iso{\textsc{iso}~}
+
+\def\iata{\textsc{iata}}
+\def\iso{\textsc{iso}~}
+
+
+\def\totalmarks{35}
+\def\partonemarks{15}
+\def\parttwomarks{20}
+
+
+# Project Admin
+
+For project administrative matters and rules, refer to the phase 1 project specification.
+
+# Deliverables (\parttwomarks{} marks total)
+
+There are three deliverables for phase 2 of the CITS5501 project:
+
+- A text file containing an EBNF grammar. The grammar must compile using the [BNF
+  Playground][bnf-playground] website.
+- A report (submitted as PDF), created from a Markdown file.
+- Your Java source code with Javadoc for a JUnit test class, `SegmentSubcommandTest.java`
+
+The source for all three deliverables should be checked into version control in your GitHub
+repository. We will use the submitted version for marking, but your facilitator may inspect
+the GitHub repository for additional information on your group's collaboration and quality
+assurance processes.
+
+
+[bnf-playground]: https://bnfplayground.pauliankline.com
+
+# Task 4 -- Tachi commands
+
+## Task 4.1 -- Command grammar (3 marks)
+
+Create a BNF or EBNF grammar that will parse (or generate) valid \travelsystem{}
+commands. Your grammar should be a plain text file (not MS Word, Markdown,
+or any other format).
+
+Requirements for the grammar are as follows:
+
+1.  The syntax for \travelsystem{} commands is
+    described in the Phase 1 specification, under "\travelsystem{} command description".
+2.  Your grammar should use the notation accepted by the [BNF Playground][bnf-playground] website.
+3.  You should not attempt to validate semantic properties of commands.
+4.  The grammar should include a non-terminal,
+    `<tachi_command>`, to be used as the start symbol for the grammar.
+5.  The grammar SHOULD specify any whitespace that needs to appear
+    between other symbols in the command. But as a simplifying assumption:
+    if symbols need to be separated by horizontal whitespace (tabs and spaces),
+    you can and should assume that a single space character is sufficient.
+6.  Your grammar is a code artifact, and should be clear and well-presented, like any code.
+
+\newpage
+
+**Tips:**
+
+1.  Make sure you read the [BNF playground][bnf-playground] website thoroughly -- it includes a
+    description of the dialect of EBNF it uses, under "Grammar Help".
+2.  Read through the CITS5501 [rubric guide][rubric] on "Long answer" questions requiring code.
+    Make sure you understand how those guidelines apply to EBNF grammars. (Your facilitator
+    may be able to provide some assistance.) Ensure you know how to comment your grammar,
+    structure it so it is clear to a reader, and make use of appropriate use of EBNF features
+    which would make your grammar clearer or more concise.
+
+[rubric]: https://cits5501.arranstewart.io/faq/#marking-rubric
+
+**Submission**: You will submit your grammar as a text file in Moodle. You should also
+maintain it as a file within your project repository, so markers can see how it has been
+revised and reviewed.
+
+## Task 4.2 -- Command grammar quality (3 marks)
+
+Briefly explain (word limit: 1000 words) how you ensured your grammar from Task 4.1 is:
+
+- correct;
+- clear; and
+- succinct.
+
+What high-level strategies/approaches did you use? What concrete techniques did you apply?
+Did you adopt any coverage criteria, and if so, which ones and why?
+You should link to at least one point in your project repository where the grammar has been
+reviewed for quality.
+
+You should discuss the degree to which your quality assurance techniques can be _automated_ --
+could they be run automatically when changes are made to the code, or do they require manual
+steps? If the latter, discuss whether this would be appropriate for a real-world project,
+and what improvements could be made to them.
+
+**Submission**: This should be a section in your report, and be given the heading "Task 4.2".
+
+# Task 5 -- Java testing
+
+For Task 5, you are provided with a Java library (in the form of several JAR files)
+containing compiled code and documentation for classes that
+process \travelsystem{} commands. The JAR files can be downloaded
+[here](https://cits5501.arranstewart.io/project/tachi-jar-files.zip).
+You are required to discuss approaches to testing the library and to implement several tests.
+
+The JAR files are intended to be used by adding them to a Java project. (How this is done
+depends on your exact project setup and/or IDE, but if using VS Code, it should be sufficient
+to add them to a `lib` directory that is a sibling of any `test` directory you create to
+contain your JUnit test class.)
+
+## Task 5.1 -- `ShopFlightFareCommand` class analysis (3 marks)
+
+Describe in detail the preconditions and postconditions of the
+constructor for the `ShopFlightFareCommand` class, justifying your
+answer (word limit: 500 words).
+
+**Submission**: This should be a section in your report, and be given the heading "Task 5.1".
+
+## Task 5.2 -- Input Space Partitioning (4 marks)
+
+Apply Input Space Partitioning (ISP) to two methods or constructors
+in the Java library. One of these should be
+the `SegmentSubcommand` constructor; the other can be a method or constructor
+of your choice.
+
+Explain the steps you took in applying ISP (word limit: 1000 words). Your explanation should
+include:
+
+- a level of coverage you think your test cases should achieve, and why you chose that level;
+  and
+- the characteristics and partitions you derived.
+
+Your descriptions of characteristics and partitions can be fairly brief (bullet points,
+tables, etc. are sufficient), but you should pick three characteristics to discuss in more detail. Explain
+how you arrived at those characteristics and partitions, and what the rationale for them is.
+
+You need only refine your characteristics and partitions into *four* test cases. At least
+three test cases should be for the `SegmentSubcommand` class. You should
+provide descriptions of those test cases. The test case descriptions should include:
+
+1.  A test ID, for easy reference later.
+2.  A description of all fixtures, test values and expected values.
+
+If you need to make any reasonable assumptions in order to derive your characteristics or test cases,
+state clearly what they are.
+
+**Submission**: This should be a section in your report, and be given the heading "Task 5.2".
+
+## Task 5.3 -- Test implementation (4 marks)
+
+Write a test class using JUnit 5 called
+`SegmentSubcommandTest`. The test class should contain JUnit test methods
+for the `SegmentSubcommand` class, which implement the 3--4 test cases you described in Task 5.2.
+
+Your test cases should follow appropriate best practices for JUnit tests, including:
+
+- Your tests must properly "Arrange, Act and Assert" your test case. Tests that
+  (for instance) contain no assertions will not be awarded marks.
+- Your test cases must be ones described in Task 5.2. For each test,
+  include Javadoc documentation providing the test ID from Task 5.2
+  that it corresponds to.
+
+Your code should compile using a recent version of the Java Development Kit
+and the JUnit libraries. (You may assume that the current Long-Term Support release of the
+Java Development Kit, JDK 21, is acceptable, as is the current version of the JUnit Jupiter
+library, 5.13.4.)
+ 
+**Submission**: You should submit your `SegmentSubcommandTest` Java code via Moodle.
+Refer to the Moodle site for further submission details.
+
+## Task 5.4 -- Test quality (3 marks)
+
+Explain how you assessed the quality of the tests from Task 5.3 (word limit: 500 words).
+
+You should include links to your GitHub repository (to specific pull requests, issues,
+commits, etc.) which demonstrate the tests being reviewed for quality.
+
+**Submission**: This should be a section in your report, and be given the heading "Task 5.4".
+
+<!--
+  vim: tw=94
+-->

assets/project/project-spec-2025-phase-2.pdf

@@ -0,0 +1,160 @@
+CITS5501/CITS3501 Project 2025 phase 2
+Version:
+
+0.1
+
+Date:
+
+August, 2025
+
+PROJECT ADMIN
+For project administrative matters and rules, refer to the phase 1 project
+specification.
+
+Tasks for Project Deliverable 2 [ 25 marks ]
+Answes to the following questions should be submitted via Moodle. A more
+detailed marking rubric will also be available on Moodle. Some of the questions
+require you to write English answers; others require you to write code.
+** TODO** 25 marks.
+- continue question numbers from part 1 - are these questions suitable for
+groups? - should we mark based on evidence of quality assurance through
+effective use of issues and pull requests and reviews - possible genAI question
+- get them to use genAI to generate a set of test cases and then critique them
+using their pull request rules (including a review)
+Question 4 [4 marks] YES
+Write a BNF or EBNF grammar that will parse (or generate) valid
+gladius commands. Your grammar should use the notation accepted
+by the BNF playground. Your ansewr must present your grammar in
+plain text which could be pasted into the BNF playground and compiled
+without error.
+The grammar should include a non-terminal <gladius_command> to
+be used as the start symbol for the grammar. The grammar should
+specify any whitespace that needs to appear between other symbols in
+1
+
+the command. (As a simplifying assumption, you may assume that a
+single space character is sufficient as a separator between words.)
+Question X [4 marks] NO
+Write a static Java method, countTerminalSymbols, which counts the
+terminal symbols in a grammar.
+
+The signature for the method should be: static int countTerminalSymbols(List<String
+The input will be a grammar in BNF or EBNF format (specifically, the
+notation accepted by the BNF playground), split into meta-symbols
+– each element of the List<String> will be one meta-symbol. Metasymbols consist of terminal symbols (the double quote marks are included in the meta-symbol), non-terminal symbols (the angle brackets
+are included in the meta-symbol), newlines, and other meta-syntactic
+symbols used by the EBNF playground (such as the “is-defined-as”
+symbol, ::= or the “alternative” or “or” symbol, |.)
+For example, the following List<String> would represent a very small
+grammar consisting of just two strings, sat and sun:
+List<String> myGrammar =
+List.of("<weekendDay>", "::=", "\"sat\"", "|", "\"sun\"");
+The countTerminalSymbols() method would return the int 2 given
+the grammar myGrammar.
+You may assume that java.util.* and java.util.regex.* import
+statements appear at the top of the source file for your code.
+Question X [4 marks] NO
+Would it be possible to exhaustively test the syntax of gladius
+commands (that is, to write tests which have derivation coverage)?
+Why or why not? What about if we restricted ourselves to just the
+shop flight fare command? Give reasons for your conclusions.
+(Maximum 500 word answer.)
+Question X [4 marks] NO
+
+2
+
+Write a static Java method, countProductions, which counts the number of productions in a grammar (see the Amman and Offutt text for a
+definition of “production”).
+The signature for the method should be: static int countProductions(List<String>).
+The input will be a grammar in BNF or EBNF format (specifically, the
+notation accepted by the BNF playground), as detailed in question 2.
+Your may assume that java.util.* and java.util.regex.* import
+statements appear at the top of the source file for your code.
+
+3
+
+Question 5 [4 marks] YES
+Describe in detail the preconditions and postconditions of the
+constructor for the ShopFlightFareCommand class, justifying your
+answer. (Max 500 words)
+Question 6 [10 marks] YES
+Apply Input Space Partitioning (ISP) to the constructor for the
+SegmentSubcommand constructor, explaining in detail the steps you
+take and what characteristics and partitions you would use.
+You should describe:
+• eight characteristics that would be useful for testing the constructor.
+• three test cases in detail, including all fixtures, test values and
+expected values. Include a test ID for each test case, so you can
+refer to it in question 7.
+You need not exhaustively describe all characteristics, partitions, test
+cases and values that would be needed, but should briefly discuss what
+more would be needed – beyond the eight characteristics and three test
+cases you have described – to achieve Base Choice Coverage, and how
+you would know when it was achieved.
+(Max 1000 words)
+Question 7 [12 marks] YES
+Write a test class using JUnit 5 called SegmentSubcommandTest, which
+contains @Test methods which implement the three test cases you
+described in question 6. Skeleton code for this class is provided in the
+supplied Java code, in the “test” directory.
+TODO OR get them to generate test cases with an AI tool and then review
+the test cases. Issues should be use to track problems with the generated test
+cases.
+Your test cases should implement all appropriate best practices for
+unit tests.
+4
+
+Note that to obtain any marks, it is a requirement of the question that:
+- you implement three of your question 6 test cases -- for each test,
+include Javadoc documentation providing the test ID from question 6
+which it corresponds to. If you implement something else instead, no
+marks will be awarded.
+- your tests properly "Arrange, Act and Assert" your test case. Tests that
+(for instance) contain no assertions will not be awarded marks.
+The code checks available via Moodle can be useful to highlight
+possible problems in your code, but passing them is not a guarantee of any
+marks being awarded.
+Question 8 [4 marks] YES
+Describe a set of test cases for the CommandParser.parse() method
+which have production coverage of the grammar you specified as an
+answer to question 1. Explain why it is that your test cases satisfy this
+coverage criterion.
+TODO Should they write these test cases?
+max 1000 words
+Question 10 [4 marks] NO
+Your colleague Oreb has been reading about logic-based testing, and
+wonders whether it would be a good use of time to assess – once an
+initial suite of tests is in place – what level of coverage the tests for the
+gladius system have (e.g. do they have Active Clause Coverage)?
+Answer the following question: Would measuring logic-based coverage
+for the gladius system be a good use of the team’s time? Why or why
+not? Explain your reasoning.
+
+Extension tasks
+You may submit an answer to either of the following questions for 3 bonus
+marks, awarded at the discretion of the unit coordinator based on the coher5
+
+ence and quality of the answer. These 3 bonus marks cannot take your final
+mark higher than 35.
+• How could mutation testing be used to evaluate the quality of your
+team’s tests, and what empirical evidence exists that mutation testing is
+a sound approach to evaluating test quality? If you conclude mutation
+testing is not a sound approach, suggest alternatives, and explain your
+reasoning. Your answer should include appropriate academic references.
+• Write a parser and read–eval–print (REPL) loop for the command
+syntax described in this project specification, in any language of your
+choosing that can be compiled and run on an Ubuntu 20.04 distribution
+running on AMD64 processors. Your REPL loop may return canned
+responses to commands.
+Commands for building and running your program should be uploaded
+as an image to the Docker Hub or any other publicly available Docker
+repository, so that the program can be run using a docker run command.
+Your Moodle answer should explain what testing approaches you adopted
+while writing the program, give a URL on a repository for the source
+code, and include the details of the docker run command needed to
+run it. (Note: ensure you keep your source code repository private until
+the marker requests access, as this is an individual project.)
+
+6
+
+