Auto-insert basic xrefstyle attribute before first section

[AryaHassanli]

Summary
This PR updates the disco-ball formatting pipeline to ensure that all AsciiDoc spec documents define an xrefstyle attribute before their primary top-level section. If an xrefstyle directive is already present, it is left untouched.

Details

• Added AddXrefstyle Option: Introduced a new boolean flag AddXrefstyle to DiscoOptions(disco/option.go) (defaulting to true). This allows the logic to be toggled off via the CLI (--no-add-xrefstyle) if necessary.
• Conditional Insertion Logic: Updated discoBallTopLevelSection(disco/baller.go) in disco/baller.go to scan the document elements before the first section (topLevelSection).
• AST Integrity: If no xrefstyle AttributeEntry is found, the pipeline safely constructs one with the value "basic" (:xrefstyle: basic) and injects it immediately before the top index, appending an asciidoc.NewLine{} to maintain proper document rendering spacing.

Related Issues
Fixes #49

Testing

• Verified that compiling and running alchemy disco successfully injects :xrefstyle: basic on target documents without overriding existing custom xrefstyle directives (e.g., :xrefstyle: short).
• Verified that no file (except for orphaned ones) remained without xrefstyle using the following script:

#!/usr/bin/env python3
import os
import sys
import re

def check_file(filepath):
    """
    Checks if a .adoc file has a :xrefstyle: attribute before its first section header.
    Returns (True, None, None) if condition is met or no sections exist.
    Returns (False, line_num, line_content) if a section header is found before :xrefstyle:.
    """
    has_xrefstyle = False
    
    try:
        with open(filepath, 'r', encoding='utf-8') as f:
            for line_num, line in enumerate(f, 1):
                raw_line = line.strip()
                
                if raw_line.startswith(':xrefstyle:'):
                    has_xrefstyle = True
                    break
                
                # In AsciiDoc, a section header starts with one or more '=' followed by a space.
                if re.match(r'^=+\s', raw_line):
                    if not has_xrefstyle:
                        return False, line_num, raw_line
                    break # Stop checking after first section
                    
    except Exception as e:
        print(f"Failed to read {filepath}: {e}", file=sys.stderr)
        return True, None, None  # Skip unreadable
        
    return True, None, None

def main():
    directory = sys.argv[1] if len(sys.argv) > 1 else '.'
    all_good = True
    
    for root, dirs, files in os.walk(directory):
        for file in files:
            if file.endswith('.adoc'):
                filepath = os.path.join(root, file)
                
                ok, line_num, line_content = check_file(filepath)
                if not ok:
                    # Print relative path for cleaner output if starting from '.'
                    rel_path = os.path.relpath(filepath, directory)
                    print(f"Error in {rel_path}: First section starts at line {line_num} ('{line_content}') without preceding ':xrefstyle:'.")
                    all_good = False
                    
    if all_good:
        print("Success: All .adoc files have :xrefstyle: before their first section.")
        sys.exit(0)
    else:
        sys.exit(1)

if __name__ == '__main__':
    main()

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request enhances the disco-ball formatting pipeline by ensuring that all AsciiDoc specification documents automatically include an xrefstyle attribute set to basic if one is not already present. This change standardizes cross-reference styling across documents while providing an option to disable this behavior.

Highlights

• New Option for Xrefstyle Insertion: A new boolean flag, AddXrefstyle, was introduced to DiscoOptions (in disco/option.go). This option, defaulting to true, allows the automatic insertion of the xrefstyle attribute to be toggled via the CLI using --no-add-xrefstyle.
• Conditional Xrefstyle Insertion Logic: Logic was added to discoBallTopLevelSection (in disco/baller.go) to scan document elements before the first section. If no xrefstyle attribute is found, a new one with the value basic (:xrefstyle: basic) is safely constructed and injected immediately before the top index, followed by a newline for proper rendering.
• AST Integrity Maintained: The implementation ensures that existing xrefstyle directives are not overridden, and the new attribute is inserted in a way that maintains the document's Abstract Syntax Tree (AST) integrity and rendering spacing.

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces a useful feature to automatically add the :xrefstyle: basic attribute to AsciiDoc files if it's not present before the first section. The implementation is logical and correctly handles the described cases. The changes in disco/option.go to add a toggle for this feature are also well-implemented. I have one suggestion in disco/baller.go to improve the performance of the slice manipulation, which could be beneficial for large documents.

[AryaHassanli]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces a new feature to the disco-ball formatting pipeline that automatically inserts a basic xrefstyle attribute before the first section of AsciiDoc spec documents if one is not already present. The changes include adding a new boolean option AddXrefstyle to control this behavior and updating the discoBallTopLevelSection function to implement the insertion logic. The code changes appear to be well-structured and include a test case to verify the new functionality. However, there are a few areas where improvements can be made to enhance code clarity and efficiency.