brut 0.14.0 → 0.15.0

data/docs/assets/ai.md.Cy9GWnER.js

@@ -1 +0,0 @@
-import{_ as t,c as o,o as a,ag as i}from"./chunks/framework.1L-BeKqY.js";const b=JSON.parse('{"title":"AI Declaration and Notes","description":"","frontmatter":{},"headers":[],"relativePath":"ai.md","filePath":"ai.md"}'),s={name:"ai.md"};function r(n,e,l,d,h,c){return a(),o("div",null,e[0]||(e[0]=[i('<h1 id="ai-declaration-and-notes" tabindex="-1">AI Declaration and Notes <a class="header-anchor" href="#ai-declaration-and-notes" aria-label="Permalink to &quot;AI Declaration and Notes&quot;">​</a></h1><p>LLMs and AI tools are a current fact of life. We feel it&#39;s important to be realistic and up front about how they affect this project.</p><h2 id="levels-of-ai-use" tabindex="-1">Levels of AI Use <a class="header-anchor" href="#levels-of-ai-use" aria-label="Permalink to &quot;Levels of AI Use&quot;">​</a></h2><p>I created <a href="https://declare-ai.org/" target="_blank" rel="noreferrer">declare-ai.org</a> to allow precise documentation of how AI is used in a project. It defines four levels of AI use:</p><ol><li>No involvement at all.</li><li>Non-create assistance, such as the completions GitHub Copilot may make while you are typing.</li><li>Creative assistance, where an AI generated a large amount of code that you then modified. An example would be using a tool like Cursor to write code for your review.</li><li>Completely Produced by an AI, for example if you used Stable Diffusion to create your icon.</li></ol><h2 id="code" tabindex="-1">Code <a class="header-anchor" href="#code" aria-label="Permalink to &quot;Code&quot;">​</a></h2><p>The entirety of Brut&#39;s codebase could be grouped into three parts:</p><ul><li>The library code developers use. This is, roughly, the code in <code>lib</code>, <code>brut-js/src</code>, and <code>brut-css/src</code>.</li><li>Tests of the library code.</li><li>Tools used to manage the library code, such as what&#39;s in <code>bin/</code>, <code>brut-js/bin</code>, <code>brut-css/bin</code>, etc.</li></ul><h3 id="library-code-should-be-written-by-a-person" tabindex="-1">Library Code Should Be Written By a Person <a class="header-anchor" href="#library-code-should-be-written-by-a-person" aria-label="Permalink to &quot;Library Code Should Be Written By a Person&quot;">​</a></h3><p>We want the library code written by a person, i.e. it should have level 1 AI assistance: none. As of this writing—June 17, 2025—all library code was written by a person.</p><p>If some code is level 2—non-creative assistance—that is probably fine.</p><h3 id="tests-should-not-be-totally-written-by-ai" tabindex="-1">Tests Should Not Be Totally Written by AI <a class="header-anchor" href="#tests-should-not-be-totally-written-by-ai" aria-label="Permalink to &quot;Tests Should Not Be Totally Written by AI&quot;">​</a></h3><p>As of this writing—June 17, 2025—the library has no automated tests. The <code>adrs.cloud</code> app serves as the test suite.</p><p>That said, as tests are developed, they must never be written entirely by an AI without human review (level 4). Our preference is that all tests comply with level 1 or level 2, however we are open to creative assistance for tests as might be provided by a tool like Cursor.</p><p>In any case, the author of a test should understand it and the maintainers must be able to understand and modify all tests without the use of AI tools.</p><h3 id="management-tools-should-not-be-totally-written-by-ai" tabindex="-1">Management Tools Should Not Be Totally Written by AI <a class="header-anchor" href="#management-tools-should-not-be-totally-written-by-ai" aria-label="Permalink to &quot;Management Tools Should Not Be Totally Written by AI&quot;">​</a></h3><p>Like tests, management tools must be comprehensible by a person and the creator of the code must understand it. That said, some of the tools were created with level 3 AI assistance, and we expect these tools may continue to be created this way.</p><p>Nevertheless, this code must be reviewed and understood by a person.</p><h2 id="documentation" tabindex="-1">Documentation <a class="header-anchor" href="#documentation" aria-label="Permalink to &quot;Documentation&quot;">​</a></h2><p>We strive to have all documentation written by a real person. None of this documentation, or the API documentation, is produced by a machine, although spelling and grammar corrections will certainly have been suggested by automated tools.</p><p>We expect an LLM to be able to digest this documentation and source code and provide alternate analysis of how Brut works and how to use it. We hope such analysis is correct and useful, however that cannot be guaranteed, so this documentation is the second best source of truth, the source code being the best.</p><h2 id="logos" tabindex="-1">Logos <a class="header-anchor" href="#logos" aria-label="Permalink to &quot;Logos&quot;">​</a></h2><p>While the various logos look like someone typed &quot;make me a logo in the style of the Washington, DC Metro&quot;, if you look closely, you will see the telltale sings that they were made by a person…a person who is not a professional designer.</p><p>As such, these are all Level 1.</p><h2 id="ai-information-about-brut-should-be-viewed-with-skepticism" tabindex="-1">AI Information about Brut Should Be Viewed with Skepticism <a class="header-anchor" href="#ai-information-about-brut-should-be-viewed-with-skepticism" aria-label="Permalink to &quot;AI Information about Brut Should Be Viewed with Skepticism&quot;">​</a></h2><ul><li><strong>Answers from an LLM about Brut are likely incorrect.</strong> LLMs will certainly not have been trained on information about Brut, since it is new.</li><li><strong>Code Completions of Brut Code are suspect.</strong> I have observed that e.g. GitHub CoPilot is capable for properly completing Brut code if there is enough context, but it is not capable of, say, creating a component from scratch. <strong>Review all Code Completions Carefully</strong>.</li></ul>',26)]))}const p=t(s,[["render",r]]);export{b as __pageData,p as default};

data/docs/assets/ai.md.Cy9GWnER.lean.js

@@ -1 +0,0 @@
-import{_ as t,c as o,o as a,ag as i}from"./chunks/framework.1L-BeKqY.js";const b=JSON.parse('{"title":"AI Declaration and Notes","description":"","frontmatter":{},"headers":[],"relativePath":"ai.md","filePath":"ai.md"}'),s={name:"ai.md"};function r(n,e,l,d,h,c){return a(),o("div",null,e[0]||(e[0]=[i("",26)]))}const p=t(s,[["render",r]]);export{b as __pageData,p as default};

data/docs/assets/assets.md.7C3HWkga.lean.js

@@ -1 +0,0 @@
-import{_ as e,c as a,o as i,ag as t}from"./chunks/framework.1L-BeKqY.js";const u=JSON.parse('{"title":"Assets","description":"","frontmatter":{},"headers":[],"relativePath":"assets.md","filePath":"assets.md"}'),n={name:"assets.md"};function o(h,s,l,r,p,d){return i(),a("div",null,s[0]||(s[0]=[t("",39)]))}const k=e(n,[["render",o]]);export{u as __pageData,k as default};

data/docs/assets/brut-js.md.B4GYxQVw.lean.js

@@ -1 +0,0 @@
-import{_ as t,c as a,o as s,ag as o}from"./chunks/framework.1L-BeKqY.js";const i="/assets/spa.qejUdp-5.png",m=JSON.parse('{"title":"BrutJS","description":"","frontmatter":{},"headers":[],"relativePath":"brut-js.md","filePath":"brut-js.md"}'),n={name:"brut-js.md"};function r(l,e,d,h,c,p){return s(),a("div",null,e[0]||(e[0]=[o("",35)]))}const g=t(n,[["render",r]]);export{m as __pageData,g as default};

data/docs/assets/business-logic.md.BY4hGy0m.js

@@ -1 +0,0 @@
-import{_ as o,c as a,o as s,ag as t}from"./chunks/framework.1L-BeKqY.js";const m=JSON.parse('{"title":"Business or Domain Logic","description":"","frontmatter":{},"headers":[],"relativePath":"business-logic.md","filePath":"business-logic.md"}'),n={name:"business-logic.md"};function i(c,e,r,d,l,u){return s(),a("div",null,e[0]||(e[0]=[t('<h1 id="business-or-domain-logic" tabindex="-1">Business or Domain Logic <a class="header-anchor" href="#business-or-domain-logic" aria-label="Permalink to &quot;Business or Domain Logic&quot;">​</a></h1><p>Since business and domain logic is not required, nor encouraged, to go in your data models, where does it go?</p><p>It can go anywhere you like - Brut is not currently prescriptive.</p><h2 id="overview" tabindex="-1">Overview <a class="header-anchor" href="#overview" aria-label="Permalink to &quot;Overview&quot;">​</a></h2><p>It&#39;s recommended that you place classes in <code>app/src/back_end</code>. Any directory created in there will be auto-loaded by Brut/Zeitwerk based on its rules. This means that classes in any directory in <code>app/src/back_end</code> should not be namespaced.</p><p>For example, if you have <em>commands</em> and <em>queries</em>, you may want them in <code>app/src/back_end/commands</code> and <code>app/src/back_end/queries</code>, respectively. In this case, <code>NewOrganizationCommand</code> would go in <code>app/src/back_end/commands/new_organization_command.rb</code> and <code>AccountQuery</code> would go in <code>app/src/back_end/queries/account_query.rb</code></p><p>Or, you could could organize them into <code>app/src/back_end/business_logic/commands</code> and <code>app/src/back_end/business_logic/queries</code>. In that case, <code>Commands::NewOrganization</code> would be expected in <code>app/src/back_end/business_logic/commands/new_organization.rb</code> and <code>Queries::Account</code> would be expected in <code>app/src/back_end/business_logic/queries/account.rb</code>.</p><p>How you organize it is up to you.</p><h2 id="testing" tabindex="-1">Testing <a class="header-anchor" href="#testing" aria-label="Permalink to &quot;Testing&quot;">​</a></h2><p>Tests can be written using RSpec in the usual way. Spec files should be in <code>specs/back_end/path/to/class.spec.rb</code>. Note that Brut expects Spec files to end in <code>.spec.rb</code> and <em>not</em><code>_spec.rb</code>.</p><p>There is nothing special about the tests for your domain logic. Write them however you need to.</p><h2 id="recomended-practices" tabindex="-1">Recomended Practices <a class="header-anchor" href="#recomended-practices" aria-label="Permalink to &quot;Recomended Practices&quot;">​</a></h2><p>This could be an entire series of books. The main recommendation is to take a light approach and don&#39;t immediately install complex frameworks or libraries unless you know you need them.</p><p>Something somewhere in your business logic will need to interface with your front-end. The simplest way to do that is to allow form objects to be passed into your back-end. The second simplest way is to pass form values into your back-end.</p><p>You are strongly discouraged from having your front-end locate data models and pass those to your back-end. This can be done while prototyping and for fast iteration on a concept, but generally you do not want to query your database from your handlers or pages just to pass the results into a back-end class.</p><p>Exposing data models to the front-end is generally OK, as that is sometimes what you need to do.</p><h2 id="technical-notes" tabindex="-1">Technical Notes <a class="header-anchor" href="#technical-notes" aria-label="Permalink to &quot;Technical Notes&quot;">​</a></h2><div class="important custom-block github-alert"><p class="custom-block-title">IMPORTANT</p><p>Technical Notes are for deeper understanding and debugging. While we will try to keep them up-to-date with changes to Brut&#39;s internals, the source code is always more correct.</p></div><p><em>Last Updated May 7, 2025</em></p><p>Creating universal abstractions from business logic is difficult. Brut is unlikely to do this. If it does, it will be after much analysis of exsiting patterns and <em>only</em> if it helps avoid mistakes and increases developer throughput.</p>',20)]))}const h=o(n,[["render",i]]);export{m as __pageData,h as default};

data/docs/assets/business-logic.md.BY4hGy0m.lean.js

@@ -1 +0,0 @@
-import{_ as o,c as a,o as s,ag as t}from"./chunks/framework.1L-BeKqY.js";const m=JSON.parse('{"title":"Business or Domain Logic","description":"","frontmatter":{},"headers":[],"relativePath":"business-logic.md","filePath":"business-logic.md"}'),n={name:"business-logic.md"};function i(c,e,r,d,l,u){return s(),a("div",null,e[0]||(e[0]=[t("",20)]))}const h=o(n,[["render",i]]);export{m as __pageData,h as default};