Skip to content

Review for usability #1

Closed
Closed

Description

@jonverrier

Review the code for comprehensibility to newcomers - we will publish this on hackernews at some point.

Activity

  1. jonverrier commented on Mar 12, 2026

    @jonverrier
    OwnerAuthor

    @cursoragent can you look at this?

  2. jonverrier commented on Mar 12, 2026

    @jonverrier
    OwnerAuthor

    @claude please pick this up

  3. claude commented on Mar 12, 2026

    @claude

    Claude finished @jonverrier's task in 1m 51s —— View job


    Code Review: Usability for Newcomers

    Tasks:

    • Gather context and understand request
    • Read repo structure and all source files
    • Review code for newcomer comprehensibility
    • Provide detailed feedback

    Overall the README and code are well-structured with clear JSDoc. There are a handful of issues — ranging from a concrete bug to naming conventions — that would trip up newcomers.


    1. Bug: Misplaced generated comment in C4DiagramVisitor.ts

    File: src/C4DiagramVisitor.ts, lines 79–94

    The auto-generated StrongAI comment was inserted between the JSDoc for formatDateYYYYMMDD and the function body itself:

    /**
     * Formats a Date as a compact YYYYMMDD string.
     */
    // ===Start StrongAI Generated Comment (20260219)===
    // Generates C4 architecture diagram README files...
    // ===End StrongAI Generated Comment===
    function formatDateYYYYMMDD(date: Date): string {

    The generated comment belongs at the top of the file (after the @module JSDoc block), not sandwiched into a standalone helper function. A newcomer reading this file would find the comment very confusing — it describes the whole module but appears to annotate a date-formatting function. This is arguably the most visible self-referential issue: the tool that generates docs for other projects has mislabelled its own source.


    2. Invalid UUIDs in src/PromptIds.ts

    c4ComponentDiagramPromptId and c4ContextDiagramPromptId contain the characters g and h, which are not valid hexadecimal digits:

    export const c4ComponentDiagramPromptId  = 'b2e5f8a3-4c9d-5g1f-0e3b-6d7c8f9g2b3c';
    export const c4ContextDiagramPromptId    = 'c3f6g9b4-5d0e-6h2g-1f4c-7e8d9g0h3c4d';

    These are not valid UUIDs. moduleHeaderCommentPromptId is a well-formed UUID; the other two are not. If the prompt repository validates UUID format, lookups would silently fail. Even if it doesn't, the comment at the top of the file says "Do not change these UUIDs unless Prompts.json is updated in lockstep" — a newcomer would trust these as correct. Worth fixing in Prompts.json as well.


    3. Code duplication across ModuleHeaderVisitor.ts and C4DiagramVisitor.ts

    Both files independently redeclare:

    • MS_PER_DAY = 86400000 (lines 39 / 49)
    • TIME_WINDOW_DAYS: Record<ETimeWindow, number> (lines 42–46 / 52–56)
    • formatDateYYYYMMDD(date: Date): string (lines 73–78 / 89–94)
    • parseDateYYYYMMDD(s: string): Date | null (lines 83–94 / 99–109)

    A newcomer making a change to one copy would likely miss the other. These four items belong in a shared internal utility module (e.g., src/DateUtils.ts) or in DocGenTypes.ts.


    4. k-prefixed enum values are an unusual TypeScript convention

    Every enum uses a k prefix (e.g., kOneWeek, kComponent, kFirst):

    export enum ETimeWindow {
       kOneWeek  = 'kOneWeek',
       kTwoWeeks = 'kTwoWeeks',
       kOneMonth = 'kOneMonth'
    }

    This is a C++ convention adopted by some teams, but it's uncommon in TypeScript/JavaScript ecosystems. The TypeScript handbook and most popular TS open-source projects use PascalCase or SCREAMING_SNAKE_CASE for enum members. For a Hacker News audience, the k prefix will look foreign. The E prefix on enum type names and I prefix on interfaces are similarly unusual to JS/TS newcomers (common in C# / older TS style), though those are at least documented conventions.

    A short note in the README (e.g., "Enums use E prefixes and k-prefixed values following the project's internal convention") would save confusion.


    5. "StrongAI" brand is unexplained

    The output files are named README.StrongAI.Component.md / README.StrongAI.Context.md, the sentinel markers read StrongAI Generated Comment, the README datestamp says StrongAIAutoDoc, and the README describes the tool as part of an ecosystem called "prompt-repository/assistant-common". None of these explain what "StrongAI" is or its relationship to C4-Auto.

    The README mentions @jonverrier/prompt-repository but doesn't link to it or summarise what it provides. A newcomer will immediately ask: "What is StrongAI? Is this a company? An internal SDK?" One sentence like "StrongAI is the internal brand name for the LLM tooling powering this project — see @jonverrier/prompt-repository" would resolve this.


    6. EModel.kLarge / EModelProvider.kOpenAI — which actual model?

    In src/VisitorFactory.ts:69:

    const chatDriver = new ChatDriverFactory().create(EModel.kLarge, EModelProvider.kOpenAI);

    A newcomer will want to know: which OpenAI model does kLarge map to? GPT-4o? o1? This matters for cost estimation and reproducibility. Either the README or an inline comment should note the current mapping (e.g., "currently GPT-4o").


    7. Missing CLAUDE.md

    There is no CLAUDE.md file in the repo. This is minor but relevant if you intend for AI-assisted contributors to work on the project; conventions like "always use k-prefixed enums" and "use @jonverrier/prompt-repository error classes" are currently only in the README spec section rather than machine-readable guidelines.


    What is working well

    • README.md is genuinely excellent — it explains C4, what the tool does, the pipeline architecture, quick-start, CLI reference, and the full spec. This is above average for an OSS CLI tool.
    • DocGenTypes.ts is a clean single source of truth for interfaces and enums, with thorough JSDoc.
    • Dependency injection (IFileReader, IFileWriter, IChatDriver) is well-applied and the tests-inject-mocks pattern is clearly explained inline.
    • DirectoryTreeTraverser.ts is clean and easy to follow.
    • Test separation (unit / integration / e2e) is well-structured and documented.

  4. jonverrier commented on Mar 13, 2026

    @jonverrier
    OwnerAuthor

    @claude please fix all these issues. Strong AI is the parent project - this repo was created to generate documentation for Strong AI. Strong AI is both a statement of belief in AI, and a brand that helps community and performance gyms deliver differentiated experiences through AI.

  5. claude commented on Mar 13, 2026

    @claude

    Claude finished @jonverrier's task in 3m 35s —— View job • claude/issue-1-20260313-2123 • Create PR ➔


    Fixing all code review issues — complete

    Tasks:

    • Gather context and read source files
    • Fix 1: Remove misplaced generated comment in C4DiagramVisitor.ts
    • Fix 2: Correct invalid UUIDs in src/PromptIds.ts and src/Prompts.json
    • Fix 3: Extract shared date utilities to src/DateUtils.ts
    • Fix 4 & 5 & 6: Update README (enum conventions, StrongAI brand, model mapping)
    • Fix 7: Create CLAUDE.md with project conventions
    • Commit and push changes

    Summary of changes

    Fix 1 — Misplaced generated comment (src/C4DiagramVisitor.ts)
    Removed the duplicate StrongAI generated comment block that was incorrectly inserted between the JSDoc for formatDateYYYYMMDD and the function body. The correct generated comment at the top of the file (after the copyright line) was preserved.

    Fix 2 — Invalid UUIDs (src/PromptIds.ts + src/Prompts.json)
    Replaced non-hex characters (g, h) in both UUIDs:

    • c4ComponentDiagramPromptId: b2e5f8a3-4c9d-5a1f-0e3b-6d7c8f9a2b3c
    • c4ContextDiagramPromptId: c3f6a9b4-5d0e-6b2a-1f4c-7e8d9a0b3c4d

    Both PromptIds.ts and Prompts.json updated in lockstep.

    Fix 3 — Code duplication (src/DateUtils.ts — new file)
    Extracted formatDateYYYYMMDD, parseDateYYYYMMDD, MS_PER_DAY, and TIME_WINDOW_DAYS into a new src/DateUtils.ts module. Both ModuleHeaderVisitor.ts and C4DiagramVisitor.ts now import from there, eliminating the four duplicated definitions.

    Fix 4 & 5 — README: StrongAI brand + naming conventions

    • Added a callout near the top of README.md explaining what StrongAI is: the parent project/brand that helps community and performance gyms deliver AI-powered experiences, and the source of the sentinel markers and file naming.
    • Added a "Code conventions" section explaining the E/I/k naming style and its C++ origins so newcomers aren't caught off guard.

    Fix 6 — README + source: model documentation

    • Added inline comment in src/VisitorFactory.ts noting that EModel.kLarge maps to gpt-4o.
    • Same mapping documented in the new "Code conventions" section of README.md.

    Fix 7 — CLAUDE.md (new file)
    Created a CLAUDE.md at the repo root covering: naming conventions, error handling policy, dependency injection pattern, prompt ID rules (valid UUID format, lockstep updates), shared utilities location, sentinel string format, and LLM model mapping.


  6. added a commit that references this issue on Mar 13, 2026
    7620512
  7. jonverrier commented on Mar 14, 2026

    @jonverrier
    OwnerAuthor

    @claude - for this issue 'File: src/C4DiagramVisitor.ts, lines 79–94

    The auto-generated StrongAI comment was inserted between the JSDoc for formatDateYYYYMMDD and the function body itself:

    /**

    • Formats a Date as a compact YYYYMMDD string.
      */
      // ===Start StrongAI Generated Comment (20260219)===
      // Generates C4 architecture diagram README files...
      // ===End StrongAI Generated Comment===
      function formatDateYYYYMMDD(date: Date): string {'
      => does this need a code fix to go with it i.e. we have fixed the issue with the comment placement, but if we re-ran the utility on itself, it would re-create the issue? If it does need a fix, please propose one.
  8. claude commented on Mar 14, 2026

    @claude

    Claude finished @jonverrier's task in 4m 3s —— View job • claude/issue-1-20260314-1506 • Create PR ➔


    Tasks:

    • Gather context
    • Read C4DiagramVisitor.ts and ModuleHeaderVisitor.ts
    • Determine if re-running recreates the misplaced comment
    • Remove the misplaced sentinel block from C4DiagramVisitor.ts

    Analysis: would re-running the utility recreate the misplacement?

    Short answer: No — the current code already has the right safeguards. No logic change is needed. The misplaced block was a historical artifact that has now been removed.

    Why re-running is safe

    ModuleHeaderVisitor handles this via two independent protections:

    1. stripGeneratedHeader loops to remove all sentinel blocks

    re.lastIndex = 0; // Reset to find next block in modified string

    It keeps scanning after each removal, so both the correctly-placed block (lines 11–17) and the misplaced block (formerly lines 82–88) would both be stripped before a new one is inserted.

    2. findInsertionPoint is limited to the first 25 lines (preamble)

    // Only search for delimiters in the preamble (avoids matching copyright or @module in later JSDoc).
    const PREAMBLE_LINE_LIMIT = 25;

    After stripping, the first 25 lines of C4DiagramVisitor.ts contain only the @module JSDoc block (lines 1–8) and the copyright line (line 9). The formatDateYYYYMMDD JSDoc at line ~72 is well outside the preamble window, so it can never be mistaken for the insertion point. The comment on PREAMBLE_LINE_LIMIT explicitly says it was added to prevent this class of bug.

    What caused the original misplacement?

    The PREAMBLE_LINE_LIMIT guard was almost certainly added after the misplacement occurred — it is a defensive fix for exactly this scenario. An earlier version of the code likely searched the full file for @module or copyright patterns, which could return a position deep in the file if those strings appeared in function JSDoc or inline comments.

    What was fixed in this commit

    Removed the duplicate sentinel block that was incorrectly inserted between the JSDoc for formatDateYYYYMMDD and the function body (src/C4DiagramVisitor.ts, lines 82–88). The correctly-placed sentinel at the top of the file (after the @module block and copyright) remains.

    · claude/issue-1-20260314-1506

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions